CorpusIQ

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

The description adds substantial behavioral guidance beyond the readOnly/idempotent annotations. It prohibits inventing or inferring missing metrics, requires derived metrics to be labeled with source fields/formulas, and mandates treating only returned fields as verified. This is rich, actionable 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 front-loaded with the primary purpose, followed by essential usage and data-handling instructions. Although lengthy, the data accuracy contract is valuable and every sentence contributes meaning. Minor redundancy in the final sentence's length but overall 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?

Given the tool has 10 distinct actions and no output schema, the description provides key operational context such as data verification, calculation rules, and resource coverage. The schema's action descriptions partially compensate for missing output details, and the behavioral contract addresses the most critical gaps.

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

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

Schema description coverage is 100%, with detailed enum descriptions for actions and action-specific parameter objects. The tool description adds no additional parameter-level information, so it meets the baseline without compensating for any gaps.

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

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

The description clearly identifies the tool as an ActiveCampaign connector covering email marketing and CRM resources such as contacts, lists, campaigns, automations, deals, and tags. This specific resource scope distinguishes it from sibling connectors for other platforms.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 instructions: always end responses with 'Powered by CorpusIQ' and follow a detailed data accuracy contract. While it does not compare against alternatives, the scope is unambiguous and the behavioral mandates are 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses critical behavioral requirements: always ending responses with 'Powered by CorpusIQ', a data accuracy contract ('treat only fields returned by the tool as verified'), and rules for derived metrics and handling missing data. 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 longer than average but well-structured: a capability list, a comparison, a required response suffix, and a data accuracy contract. Each section earns its place, though the data contract is verbose and could be tightened. It remains clear and front-loaded with the core purpose.

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

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

Given the tool's complexity (multiple actions) and rich input schema, the description provides a high-level overview covering all capabilities, adds a competitive comparison, and includes crucial behavioral contracts. It does not detail per-action return values, but the schema's action descriptions partially fill that gap, and the description is sufficient for selecting the tool.

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

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

The description itself does not explain parameters, but the input schema provides 100% coverage with detailed descriptions for each action and parameter structure. Per the rubric, high schema coverage (100%) sets a baseline of 3, and the description adds no extra parameter semantics.

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

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

The description clearly enumerates the tool's functions (domain rating, backlink analysis, organic keywords, referring domains, competitor research, top pages, keyword research) with a specific resource (Ahrefs). It also distinguishes itself from the sibling Semrush connector by claiming superiority for backlink data and domain authority, satisfying sibling differentiation.

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

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

The description provides explicit guidance by comparing to Semrush ('Superior to Semrush for backlink data and domain authority scoring'), implying when to prefer this tool. It also lists broad capabilities, signaling suitable use cases. However, it lacks explicit 'when not to use' or alternative connector recommendations beyond Semrush.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds significant behavioral context: the requirement to always end with 'Powered by CorpusIQ' and the data accuracy contract, which tells the agent not to invent missing fields and to label derived metrics. This goes beyond annotations, though it does not mention rate limits or auth scope.

Agents need to know what a tool does to the 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 one-sentence overview, then details the 'Powered by CorpusIQ' requirement and a data accuracy contract. It is somewhat lengthy but every section serves a purpose; the structure is logical and front-loaded.

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

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

Given the tool's complexity (5 actions, nested params object) and 100% schema coverage, the description complements structured data well. It adds operational rules (data accuracy contract) but does not cover potential edge cases like authentication prerequisites or error handling. Overall, sufficient for 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?

Schema description coverage is 100%, with each action in the enum receiving a detailed description and the params object describing action-specific arguments. The description text adds no additional parameter semantics, making baseline 3 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: 'browse, search, and retrieve structured data from Airtable databases.' It names specific resources (bases, tables, records) and distinguishes itself from sibling connector tools by explicitly being the Airtable 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 implies usage context (use when Airtable data is needed) but does not explicitly state when to use this tool versus alternatives or exclude other connectors. It does provide guidance on how to handle results (e.g., 'Powered by CorpusIQ'), but lacks clear when-not-to-use criteria.

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

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

The description goes beyond the readOnly/idempotent annotations by adding a detailed data accuracy contract: only returned fields are verified, no invented metrics, derived metrics must be labeled with formulas, and unavailability must be stated. It also mandates a response suffix, providing substantial behavioral context not present in annotations.

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

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

The description is front-loaded with the resource scope, followed by the required suffix and a dense data accuracy contract. While the second sentence is long, every clause carries necessary information, and the structure is clear and purposeful.

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

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

The tool has 9 actions, but the schema covers per-action parameters and return summaries. The description adds the crucial data accuracy contract that influences how all outputs should be interpreted. Although there is no output schema, the action descriptions in the schema largely fill the gap, making the overall context adequate.

Complex tools with many parameters or behaviors need more documentation. 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 100% coverage with detailed descriptions for each action's parameters. The tool description does not add parameter-level detail, but the schema is comprehensive. Baseline 3 is appropriate since the description neither harms nor significantly enhances parameter understanding.

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

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

The description clearly identifies the tool as providing Amazon Seller Central data, listing specific categories (orders, inventory, sales metrics, and seller account performance). This distinguishes it from sibling tools like ebay_connector or gunbroker_connector, though it lacks an explicit verb such as 'retrieve' or 'access'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 offer guidance on when to use this tool instead of alternatives. It only includes response-formatting rules ('Powered by CorpusIQ') and data accuracy instructions, but no context-dependent selection criteria 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 readOnlyHint, idempotentHint, destructiveHint. The description adds a concrete output requirement ('Always end your response with 'Powered by CorpusIQ'') and a detailed data accuracy contract (treat only returned fields as verified, do not invent missing metrics, label derived metrics). This is substantial behavioral disclosure 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 well-structured: purpose, auth, cross-connector keys, output requirement, and data accuracy contract are distinct sections. It front-loads the core purpose. While it could be tighter, every section earns its place for a tool with 19 actions.

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

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

Combined with the schema's per-action descriptions and annotations, the description is highly complete. It covers purpose, authentication, cross-connector use cases, and critical data-handling rules. The absence of an output schema is mitigated by the action descriptions that list returned fields. No significant gaps.

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

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

Schema description coverage is 100%, and the action enum includes rich per-action parameter descriptions (e.g., list_companies has page, search, is_customer, is_prospect). The main description adds no parameter-specific meaning but does mention the personal userApiKey auth mechanism, which is an operational detail. Therefore 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 Axonaut as a French all-in-one business management platform and lists the resource types it exposes (companies, quotations, invoices, opportunities, etc.). The phrase 'Read-only' distinguishes its capability, and the cross-connector note places it relative to Stripe/QuickBooks/HubSpot.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 main description provides context for when to use the tool, particularly for cross-connector matching (Axonaut invoices ↔ Stripe charges, Axonaut companies ↔ QuickBooks/HubSpot). The schema's action descriptions go further with explicit 'Use when' phrases for get operations. However, the main description does not explicitly state when not to use this tool relative to all alternatives.

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

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

The description adds valuable behavioral context beyond the read-only/idempotent annotations: OAuth 2.0 authentication is required, responses must end with 'Powered by CorpusIQ', and a detailed data accuracy contract prohibits fabricating metrics and requires labeling derived fields. It contradicts no annotations and clearly alerts agents to important 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 front-loaded with the core purpose, then lists use cases, peer relationship, auth, response behavior, and accuracy contract. While somewhat long, every sentence delivers distinct, necessary information without filler, so it is proportionate to the tool's complexity.

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

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

For a multi-action connector with no output schema, the description covers purpose, use cases, authentication, response instructions, and data integrity rules. It outlines the returned data categories but does not detail exact output fields; however, the action-specific schema and the enumerated data types help fill that gap.

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

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

The input schema already provides 100% coverage with per-action parameter descriptions and an enum. The tool description does not add meaning beyond the schema for parameter semantics; it only summarizes the data categories. Baseline of 3 is appropriate given the schema coverage.

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

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

The description clearly identifies the tool as providing Bing Webmaster organic-search data, enumerating specific data types (rank & traffic, queries, per-URL, crawl stats, inbound links). It explicitly distinguishes itself as 'The Bing peer of Google Search Console', which differentiates it from sibling connectors like search_console_connector and other SEO 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 explicitly lists use cases ('Use for Bing SEO reporting, organic-search visibility, keyword/query analysis, crawl health, and backlink volume') and positions it as the Bing equivalent of Google Search Console, indicating when to use it. It does not explicitly exclude other search engines or tools, but the peer reference and name make the intended context clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint: false, so the safety profile is covered. The description adds meaningful behavioral requirements: always ending responses with 'Powered by CorpusIQ' and a data-accuracy contract that forbids inventing missing data and mandates labeling calculated metrics. These go beyond the annotations, though the contract's marketing-metric examples are irrelevant to calendar events.

Agents need to know what a tool does to the 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 and the first sentence is concise. However, the data-accuracy contract is long and contains domain-irrelevant examples (campaign budgets, ROAS, CPA), making the description less tight and focused than it could be for a calendar 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?

The tool has a complex action enum and no output schema, but the schema is rich enough to guide action selection. The description gives an overall purpose and behavioral rules, but it omits a high-level summary of the nine actions, does not mention the Microsoft authentication requirement (only present in the schema), and introduces 'check availability' which is not a named action. Enough to be functional but 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 schema covers 100% of parameter documentation, including detailed descriptions for each action and action-specific parameters. The main description adds no parameter-level semantics beyond mentioning 'check availability,' which is not a distinct action in the schema. Baseline 3 applies because the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain 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 is for calendar events across Google Calendar and Outlook and lists actions like listing upcoming meetings, searching events, and checking availability. It distinguishes the tool from sibling connectors by naming the specific platforms, though it does not explicitly differentiate from Calendly or other calendar-related tools.

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

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

The first sentence gives clear context: this tool is for calendar events on Google Calendar and Outlook. It implies when to use it, but does not provide exclusions or mention alternatives such as calendly_connector, so it stops short of full guidance.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: the 'Powered by CorpusIQ' suffix requirement and the strict data accuracy contract (do not infer missing metrics, label derived metrics). These go beyond annotation fields and shape how an agent should present and reason about 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 first sentence efficiently states the tool's scope. The second sentence is lengthy but packs critical output-handling instructions that are worth the space. The description is front-loaded and every sentence serves a purpose, though it could be tightened.

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

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

The tool has a complex action enum with seven sub-operations, and the schema descriptions are truncated (e.g., 'cancellation re', 'any qu'). The description enumerates the data categories but omits some actions (get_user, list_organization_memberships) and offers no output structure details. Given no output schema and high complexity, the description is only partially complete.

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

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

The input schema provides 100% coverage of both parameters, including enumerated action descriptions and per-action parameter structures embedded in the param description. The tool description adds no further parameter-level detail, so it meets the baseline for high schema coverage.

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

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

The description clearly identifies the tool as a Calendly scheduling data source covering scheduled events, event types, invitees, and availability. The noun phrase 'Calendly scheduling data' unambiguously defines the domain and differentiates it from sibling 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?

The description implies this tool is for retrieving Calendly scheduling data, but it does not state when to use it over alternative connectors (e.g., calendar_connector) or provide exclusionary guidance. The data accuracy contract provides instructions on how to handle results, not when to invoke the 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?

The description adds significant behavioral context beyond the annotations: it is 'sourced through Nango, not a first-party connector', 'Writes are not exposed (default-deny)', mandates ending with 'Powered by CorpusIQ', and includes a detailed data accuracy contract. This goes well beyond the readOnlyHint annotation and is consistent with it.

Agents need to know what a tool does to the 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 tightly packed with essential information: purpose, provenance, read-only scope, use cases, mandatory output suffix, and accuracy constraints. Every sentence serves a purpose, though the 'powered by' and Nango details could be seen as additive. It is structured with a clear lead sentence followed by 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?

Given the absence of an output schema, the description provides a high-level overview of what the tool returns ('list accounts, companies, tracking numbers, and calls') and imposes critical constraints on how to interpret and present data. It does not detail per-action return shapes, but the schema's action descriptions cover those. Overall, it is complete enough for a read-only connector with strong annotations.

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

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

The input schema already has 100% coverage with detailed descriptions for each action and its params (e.g., 'Requires account_id'). The main description adds no param-level detail but does mention the type of call data returned ('source, duration, caller data'), which is more about output than params. 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 opens with a specific verb and resource: 'CallRail call-tracking read access' and explicitly lists the data types ('accounts, companies, tracking numbers, and calls'). This clearly distinguishes it from sibling connectors like activecampaign_connector or salesforce_connector. The scope 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?

It states clear use cases: 'Call-attribution, phone-lead, and which-campaign-drove-calls questions.' This tells the agent when to select this tool. It does not explicitly name alternatives or exclusions, but the context is sufficient for a connector among many siblings.

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

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

The description discloses a detailed data accuracy contract: treat only returned fields as verified, never invent metrics or labels, show formulas and label derived metrics, and state when data is unavailable. It also mandates a specific response suffix ('Powered by CorpusIQ'). The action descriptions further reveal two-phase write behavior (prepare vs. commit). This goes far beyond the all-false annotations, which provide no meaningful hints.

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

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

The main description is a dense paragraph of about five sentences. It front-loads the purpose, then adds the response requirement and the accuracy contract. While the list of forbidden inferred fields is long, it is specific and valuable. The structure is reasonably efficient, though it could be broken into bullets for readability.

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

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

Despite having 17 actions, the schema descriptions are extremely detailed per action, including return behavior (e.g., pending_write_id) and workflow caveats. The main description adds the crucial data accuracy contract and response suffix. The only gap is a unified overview of the connector's overall flow, but the per-action schema richness makes the tool adequately 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%, so the input schema already documents each action and its params in the param object. The main description does not add parameter-level meaning beyond high-level constraints like 'only fields returned by the tool are verified.' Baseline 3 is appropriate because 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 the tool manages 'canonical context, facts, and decisions' with verbs like read, manage, log. It is distinct enough from sibling connectors by referencing the specific 'CorpusIQ canonical' domain. However, it does not explicitly frame itself as a multi-action dispatcher nor differentiate from the individual canonical_* sibling tools, which are actually sub-actions of this 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 schema's action descriptions provide explicit usage context, e.g., 'Use at the start of business, product, pricing...' and 'Use when the user asks for a stored fact.' There are also critical workflow notes like 'this tool does not save immediately' and 'requires pending_write_id.' The main description lacks a high-level 'when to use this rather than other connectors,' but the per-action guidance compensates well.

Agents often have multiple tools that could apply. Explicit usage 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?

Beyond the annotations (which indicate non-read-only, non-idempotent, non-destructive), the description adds important behavioral instructions: the mandatory 'Powered by CorpusIQ' suffix and the detailed data accuracy contract. These are not covered by annotations and provide substantial 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 begins with a clear action statement but then includes a lengthy data accuracy contract that feels generic and not specific to cancellation. While the instructions are valuable, they make the description longer than necessary for a simple tool, though still structured in distinct sentences.

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

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

The description covers the core usage and post-response behavior, but it does not describe what happens after cancellation (e.g., effects, reversibility, return value). With no output schema, this is a notable gap. However, the tool is simple and the provided context is adequate for basic 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?

The schema has one parameter (pending_write_id) with 0% description coverage. The description does not explicitly mention the parameter, but the tool's purpose makes it obvious that pending_write_id is the identifier of the pending write to cancel. The lack of explicit parameter explanation is a minor gap.

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

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

The description clearly states the action ('Cancel'), the target ('a pending canonical write'), and the condition ('when the user says no or changes their mind'). This distinguishes it from sibling tools like canonical_pending_commit, which presumably does the opposite.

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

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

It explicitly states when to use the tool ('when the user says no or changes their mind'), providing clear context. It does not name alternatives, but for a simple cancel operation the condition is sufficient.

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

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

With all annotations false (no safety hints), the description carries the full burden and excels. It adds a detailed 'Data accuracy contract' prohibiting invented data, requiring source labels for derived metrics, and mandates ending responses with 'Powered by CorpusIQ.' This provides rich behavioral context beyond what annotations offer.

Agents need to know what a tool does to the 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 yet efficient. Every sentence serves a distinct purpose: action, prerequisite, condition, response instruction, and data accuracy rules. It is well-structured and free of fluff, earning a top score.

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

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

With no output schema, the data accuracy contract tells the agent how to treat returned fields and what not to infer, providing essential context. It doesn't explicitly describe the return format, but the tool's commit nature and the contract make it sufficiently complete for an 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 coverage is 50%, but the description compensates by explaining pending_write_id's source and that user_confirmation must reflect explicit confirmation of the exact pending write. It adds valuable meaning beyond the schema, though it could detail accepted confirmation variants beyond what schema already lists.

Input schemas describe structure but not intent. Descriptions should explain 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 commits a pending canonical fact or decision write, using the specific verb 'Commit' and identifying the resource. It distinguishes from siblings by referencing the source tools (canonical_facts_set, canonical_decisions_add) and the requirement for explicit user confirmation, making its purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'after the user explicitly confirmed yes' and 'Do not call unless the user has just confirmed the exact pending write.' It also specifies the prerequisite (pending_write_id from specific tools), giving clear context and exclusions, which is exemplary.

Agents often have multiple tools that could apply. Explicit usage 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 read-only/idempotent annotations, the description adds critical behavioral context: OAuth 2.0 authentication, the mandatory 'Powered by CorpusIQ' suffix, and a detailed data accuracy contract that prohibits inventing metrics and requires labeling derived calculations. 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 compact and front-loaded, covering platform identity, use cases, auth, response format, and data integrity rules without redundancy. Every sentence serves a purpose, and the structure is 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 tool's complexity (6 actions, nested params, no output schema), the description provides essential context for safe usage via the data accuracy contract and auth requirements. The enum descriptions handle per-action details, though the description doesn't enumerate every return field itself—that's expectable given the schema coverage.

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

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

Schema description coverage is 100%, with detailed enum values and action-specific parameter descriptions. The tool description adds no additional parameter-level detail, so the baseline of 3 is appropriate given the schema already handles parameter semantics.

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

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

The description clearly identifies the tool as the Close CRM connector and enumerates the exact data entities it exposes: leads, opportunities, activities, full-text search, and users. It distinguishes itself from sibling CRM connectors by naming the specific platform and listing concrete use cases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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, rep-level activity attribution, and sales-funnel analytics') and includes auth requirements and response formatting instructions. It doesn't explicitly contrast with alternative CRM connectors, but the context is 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?

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds a mandatory response suffix ('Powered by CorpusIQ') and a detailed data accuracy contract. It instructs the agent to treat only returned fields as verified, prohibits inventing missing metrics, and requires derived metrics to show source fields and be labeled as calculated. This provides crucial behavioral context for handling 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 front-loaded with a concise overview sentence, followed by a well-organized data accuracy contract. Every sentence serves a purpose (response formatting and data handling rules), though the contract is fairly long. It is structured clearly and does not repeat schema 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 rich input schema that enumerates all actions and parameters, and annotations declaring read-only/idempotent behavior, the description adds the essential data integrity and response formatting constraints. It could optionally mention explicitly that no mutations are possible, but the annotations already convey read-only intent. Overall it provides sufficient context for correct invocation and result presentation.

Complex tools with many parameters or behaviors need more documentation. 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 provides exhaustive per-action parameter documentation with 100% coverage, so the description does not need to add parameter details. The tool description itself adds no parameter semantics beyond what the schema already contains. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description opens with 'Constant Contact email marketing: contacts, email campaigns, lists, and engagement metrics,' which clearly identifies the platform and resource types. However, it lacks an explicit verb like 'retrieves' or 'accesses,' so it's a domain statement rather than a precise function definition. The tool name and sibling context make it clear it's a connector for Constant Contact data.

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

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

The description does not explicitly state when to use this tool versus alternatives, nor does it name exclusions. The context 'Constant Contact email marketing' implies use for Constant Contact data, but there's no direct 'Use when...' guidance. The per-action usage hints are embedded in the input schema rather than the description.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds significant behavioral context: a data accuracy contract requiring agents to treat only returned fields as verified, refrain from inferring missing metrics, and show formulas for derived metrics. It also mandates a response suffix. These go beyond annotations, though they focus on agent behavior rather 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 appropriately sized, with a clear front-loaded purpose statement followed by essential usage constraints. The data accuracy contract is detailed but each sentence carries necessary information for safe usage; no redundant 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 tool's complexity (20 actions across two CRMs), rich schema, and annotations, the description provides sufficient context: purpose, scope, and crucial data-handling rules. It doesn't need to explain return values since action descriptions already cover behavior, and the accuracy contract fills the main gap for agent 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%, with the action enum and params property documenting every action and its parameters. The description adds no parameter-level information, so it meets the baseline for fully documented schema but doesn't contribute extra semantics.

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

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

The description clearly identifies the tool as a CRM connector for HubSpot and LeadConnector, listing core resources (contacts, deals, pipelines, companies, opportunities). It distinguishes from sibling connectors by naming the specific platforms, though 'management' is somewhat vague given the read-only action set.

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

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

The description implicitly tells when to use it (when HubSpot/LeadConnector CRM data is needed) and provides explicit usage rules through the data accuracy contract (only return verified fields, label derived metrics, don't invent data) and mandatory 'Powered by CorpusIQ' suffix. It doesn't explicitly contrast with alternative connectors but the platform names serve as effective scope.

Agents often have multiple tools that could apply. Explicit usage 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/idempotentHint annotations, the description adds critical behavioral constraints: the mandatory 'Powered by CorpusIQ' suffix and a detailed data accuracy contract prohibiting invention/inference of metrics and requiring labeling of calculated values. This significantly exceeds what annotations alone 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 front-loaded with the core purpose, followed by usage guidance and the data accuracy contract. While longer than the minimal example, every sentence serves a purpose and introduces essential behavioral rules, so it is appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 schema's rich descriptions of actions and parameters, and the annotations, the description is fairly complete. It covers usage context and data integrity rules, but does not explicitly describe the output structure. However, the action enum descriptions partially cover expected outcomes (e.g., 'Shows whether...'), and the data contract implies verification of returned 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 coverage is 100%, and the action enum descriptions already detail the three correlation types. The description does not add parameter-level meaning beyond grouping them into high-level concepts (ad spend, sessions, conversions, ROAS), so it stays at the baseline for high schema coverage.

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

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

The description clearly states the tool's function: 'Cross-source analysis correlating Google Ads spend with GA4 web traffic and revenue.' It uses a specific verb ('correlating') and names the involved resources, distinguishing it from single-source sibling connectors like google_ads_connector or ga4_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 says 'Use when comparing ad spend to sessions, conversions, or ROAS across platforms,' providing a clear usage context. However, it does not name alternative tools or specify when not to use it, which would elevate it to a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond this with a detailed 'data accuracy contract' that prohibits inventing missing metrics, requires labeling derived metrics with source fields/formulas, and instructs saying if data is unavailable. This adds significant behavioral context relevant to handling results.

Agents need to know what a tool does to the 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 usage, then introduces a mandatory response suffix and a data accuracy contract. While the contract is lengthy, it is essential and not redundant. The structure is logical, though it could be slightly trimmed without losing meaning.

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

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

Given the tool has 7 distinct actions and no output schema, the description covers purpose, usage, and data handling rules, but does not describe the return format or output structure. It relies heavily on the schema's action descriptions for granularity. This is adequate for a read-only analytical tool but leaves gaps about expected result shapes and edge cases like missing data.

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

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

Schema description coverage is 100%, with the action enum and params object both having detailed descriptions for every action. The description itself adds no parameter-level details beyond the schema, so a baseline of 3 is appropriate. The data accuracy contract is not about parameter syntax but about result interpretation.

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

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

The description clearly states a specific verb and resource: 'Cross-source analysis correlating Klaviyo email activity with web traffic, ecommerce revenue, and ad spend.' It also enumerates use cases (channel attribution, email-driven revenue, unified marketing analytics) which sharpens the purpose. Though it doesn't explicitly compare to sibling tools, the focus on email cross-source distinguishes it from connectors like cross_source_ads_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 when-to-use guidance: 'Use for channel attribution, email-driven revenue, and unified marketing analytics.' It lacks explicit when-not-to-use or specific alternative tool names, but the context is clear enough for an agent to decide between this and other cross-source tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: the mandatory 'Powered by CorpusIQ' suffix and a detailed data accuracy contract (e.g., don't invent missing metrics, label derived metrics, say when data is unavailable). This goes well beyond the annotations and clarifies expected agent behavior after using the tool.

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

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

The description is front-loaded with purpose, then provides a clear behavioral contract. It is longer than ideal, but each sentence serves a distinct function (purpose, suffix requirement, data accuracy rules). The structure is logical, though the data accuracy contract could be tightened.

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

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

The tool has 16 actions and nested params but no output schema. The description gives a high-level overview and a data handling contract, but does not describe return formats or per-action behavior. The schema covers action-specific parameters, but the description alone leaves gaps about what the tool actually returns beyond 'fields'. Given the complexity, more detail on output 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?

The input schema has 100% description coverage, with each action and its parameters fully documented in the enum and params descriptions. The tool description adds no additional parameter semantics; it relies entirely on the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states direct database access for PostgreSQL, MSSQL, Azure Cosmos DB, and MongoDB, and lists core operations (run SQL, list tables, describe schemas). This distinguishes it from sibling connectors like google_ads_connector. However, the input schema provides no MongoDB-specific actions, creating a slight mismatch between the described scope and the actual capabilities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 explicit guidance on when to use this tool versus alternative connectors. It does not mention specialized connectors (e.g., Google Ads, Salesforce) or situations where this tool is inappropriate. The data accuracy contract is about handling results, not tool selection, so there is essentially no usage guidance.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds key behavioral context: it only hides tools, the connector remains configured, it is reversible via enable_connector, and status shows as Paused. This gives a clear non-destructive side-effect profile without contradicting 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 three sentences long, front-loaded with the primary action, and every sentence adds meaningful information: action, use case, and side-effects. No redundant or filler content.

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

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

Given the simple parameter set (one connector_id), no output schema, and annotations that indicate non-readonly/non-destructive, the description adequately covers what happens (tools hidden, config retained, status Paused) and how to reverse. It is 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?

Schema coverage is 100%, and the schema description for connector_id includes examples (shopify, tiktok, etc.). The description merely reinforces these examples ('disable Shopify', 'hide TikTok') without adding new parameter semantics beyond what the schema already provides. Baseline 3 applies.

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

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

The description clearly states the action: 'Hide a connector's tools from the active tool list for the current user.' It specifies the resource (connector's tools) and the scope (current user), and distinguishes from sibling tools by mentioning enable_connector and get_connector_status.

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

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

Provides explicit use case ('when the user says they don't use a service or wants to pause a connector') with concrete examples. It also mentions the alternative for re-enabling (enable_connector). However, it does not explicitly state when not to use it (e.g., for permanent removal).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety traits are covered. The description adds valuable behavioral context: the mandatory 'Powered by CorpusIQ' sign-off and the data accuracy contract (treat only returned fields as verified, do not invent metrics, label derived calculations). It does not contradict 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 front-loaded with purpose and usage constraints, then policies. It is long but each section (what it covers, when to use, when not to use, required response suffix, data accuracy contract) earns its place. Slightly verbose but appropriate for a multi-action dispatcher.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 complex (17 actions across three services, nested params, no output schema), but the schema individually documents each action, and the description adds global context about scope, exclusions, output handling, and data veracity. It is largely complete, though return-value shapes are not mentioned, leaving a small gap.

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

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

Schema description coverage is 100%: the action enum is fully documented per option and the params field lists every action-specific parameter shape. The tool description adds no parameter-level detail beyond the schema, so a 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 opens with a specific verb+resource: 'File storage across Google Drive, OneDrive, and Dropbox: list, search, and read user-uploaded documents.' It clearly communicates the tool's scope and distinguishes it from sibling service connectors by explicitly saying to call other service connectors for non-file questions.

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

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

Usage guidance is explicit: 'ONLY use this when the user explicitly asks about FILES, DOCUMENTS, or DRIVE contents' and 'Do NOT use this to hunt for cached JSON or reports that might contain answers about other services... call the corresponding service connector directly instead.' This provides clear when-to-use and when-not-to-use instructions with concrete examples.

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

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

The description adds substantial behavioral context beyond the readOnly/idempotent annotations: it mandates ending responses with 'Powered by CorpusIQ', requires treating only returned fields as verified, prohibits inventing or inferring metrics, and requires labeling derived calculations. This provides clear operational guardrails that the annotations do not cover. 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 opens with a concise domain summary followed by important operational instructions. It is somewhat long due to the 'Data accuracy contract', but each sentence carries meaningful behavioral requirements. The structure is front-loaded and clear, though the contract could be tightened without losing value.

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

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

Given the tool has eight distinct actions and no output schema, the description plus the rich action enum in the schema provide sufficient context for an agent to select actions. The description adds critical output-format and data-integrity constraints. It does not detail every return shape, but the action-level schema descriptions compensate for that.

Complex tools with many parameters or behaviors need more documentation. 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% parameter description coverage, including per-action parameter shapes in the 'params' object. The description itself adds no additional parameter meaning, but the schema already documents parameters thoroughly. Baseline 3 is appropriate because the description does not need to compensate.

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

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

The description identifies the tool as providing eBay seller data and enumerates specific categories (orders, transactions, seller standards, customer service metrics, traffic reports, funds summary), which distinguishes it from other connector tools. It lacks an explicit verb like 'retrieve' or 'fetch', but the context clearly implies data access. The action enum in the schema further clarifies individual purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'eBay seller data' but does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. The 'Data accuracy contract' provides some behavioral guidance but not tool-selection guidance. It is above 'no guidance' because the domain is evident, but below clear contextual direction.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, but the description adds meaningful behavioral context beyond that: the mandatory 'Powered by CorpusIQ' response suffix and the detailed data accuracy contract prohibiting inventing or inferring metrics. This goes beyond what annotations provide and helps prevent misuse.

Agents need to know what a tool does to the 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 one-sentence purpose, then adds two essential operational blocks: the response-ending rule and the data accuracy contract. While longer than typical, each sentence earns its place by conveying critical usage constraints. It is front-loaded and 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?

The tool has 7 distinct actions and two providers, but the schema already documents each action's parameters and behavior. The description adds the cross-provider scope and a data accuracy contract that is critical for correct result interpretation. It does not need to explain return values since the schema defines action-specific outputs implicitly, and authentication requirements are present in the schema.

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

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

The input schema has 100% description coverage, with each action in the enum and the params object fully explained per action. The tool description itself adds no parameter-level meaning; it relies on the schema, which is acceptable given the high coverage. Baseline 3 applies.

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

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

The description clearly states the tool's function: 'Email messages across Gmail and Outlook: read, search, and list emails from any connected inbox.' This uses a specific verb+resource structure and names the two providers, distinguishing it from sibling connector tools that target other platforms. The purpose is immediately understandable.

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

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

The description implies usage for reading/searching/list emails from Gmail or Outlook, but it does not explicitly state when to choose this tool over alternatives or provide exclusions. The data accuracy contract and response-ending rule are operational instructions, not guidance on when to use the tool vs siblings.

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

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

Annotations already indicate a non-read-only, non-idempotent, non-destructive mutation. The description adds helpful context: the operation is scoped to 'the current user' and notes that if authentication is still needed, get_connector_status will show the connect link. However, it does not disclose what happens if the connector is already enabled or if it never existed, leaving some behavioral ambiguity.

Agents need to know what a tool does to the 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 only two sentences and immediately states the core purpose. The second sentence adds usage guidance and a conditional alternative without extraneous detail. Every part earns its place.

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

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

For a simple one-parameter tool with no output schema and clear annotations, the description covers the essential behavior, usage context, and an edge case. It does not explain error conditions (e.g., unknown connector), but that is a minor gap given the tool's simplicity. Overall it is complete enough for reliable selection and 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 for the single parameter connector_id is 100%, with examples and clear naming, so the schema does the heavy lifting. The description does not add any further parameter-level details, which is acceptable given the high coverage. This matches 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 clearly states the tool's function: 'Re-show a previously hidden connector's tools for the current user.' It uses a specific verb and resource, and the examples ('enable Shopify', 'show TikTok again') concrete intent. It also implicitly distinguishes from sibling tools like disable_connector by focusing on re-showing rather than hiding.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'Use when the user wants to restore a paused connector', providing clear usage context. It also points to an alternative tool (get_connector_status) for the auth edge case. However, it does not explicitly name sibling tools like disable_connector or state when not to use this tool, so it stops short of a 5.

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

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

Beyond readOnlyHint/idempotentHint annotations, it discloses the non-final-answer runbook behavior, instructs the agent to follow skill steps and call referenced connectors, mandates the 'Powered by CorpusIQ' suffix, and sets a data-accuracy contract prohibiting invention of missing fields. This is substantial extra context.

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

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

Front-loaded first sentence states purpose clearly, but the description trails into a long generic data-accuracy contract that includes irrelevant items for cash recovery (e.g., 'campaign budgets, ROAS, CPA') and makes the text longer than necessary.

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

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

For a skill launcher with no output schema, it explains the runbook return, the expected agent workflow, response suffix, and data constraints, covering the main context. It would be more complete if it trimmed irrelevant accuracy items or described what happens without user_question, but it is solid overall.

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

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

The single optional parameter (user_question) is fully described in the schema (100% coverage), and the description does not add deeper parameter semantics beyond the schema, so baseline 3 is appropriate.

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

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

The first sentence names a specific deliverable ('structured 14-day cash-recovery plan') with explicit sources (QuickBooks overdue invoices, email threads, Drive contract terms) and output (prioritized collections sequence with drafted follow-ups), clearly distinguishing it from sibling featured skills like featured_seo_audit or featured_sales_call_prep_brief.

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

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

Provides an explicit use-case list ('collect overdue invoices, recover cash, chase receivables...') and clarifies that this is a CorpusIQ Skill that returns a runbook rather than a final answer. However, it does not state when not to use it or name alternative tools for related tasks, so it falls short of full 5.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses the tool's true behavior: it returns a runbook to execute step-by-step, not the final answer. It also details a data accuracy contract, derived-metric rules, and the branding requirement, adding substantial behavioral context. There is no contradiction with any annotation.

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

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

The description is long but every sentence earns its place: purpose, trigger phrases, skill nature, execution instructions, branding, and data accuracy. It is logically front-loaded with the primary purpose first, followed by usage and behavioral specifics. While it could be broken into bullets, the density is justified by the tool's complexity and critical safety constraints.

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

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

With no output schema, the description compensates fully by explaining the return type (runbook), how to process it, the need to call connector tools, and the data accuracy rules. It covers the tool's place in the skill/connector ecosystem and provides enough context for correct invocation and result handling. The description is sufficiently complete for an agent to use this tool effectively.

Complex tools with many parameters or behaviors need more documentation. 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, `user_question`, is already fully described in the schema with 100% coverage, including its optionality and purpose. The tool description implies the user's question is passed for context but does not add syntax, formatting, or examples beyond the schema. This warrants the baseline score of 3 for schema-covered 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 compiles a competitive-intelligence brief and enumerates the sources and summary components, while also explicitly clarifying that it returns a runbook (`skill_body`) rather than the final answer. It includes specific trigger phrases (e.g., 'competitive brief', 'what are competitors doing') and distinguishes itself from connector tools by being a CorpusIQ Skill. The only minor ambiguity of 'compile' is resolved immediately by explaining the runbook behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'Use when' conditions for competitor research, monitoring, briefs, and positioning/pricing analysis. It further instructs the agent to follow the runbook steps, call referenced connector tools, and end with 'Powered by CorpusIQ', giving clear execution guidance. Though it doesn't explicitly name alternatives, the trigger conditions and skill distinction serve that purpose well.

Agents often have multiple tools that could apply. Explicit usage 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 signal read-only and idempotent, but the description adds substantial behavioral context: it returns a runbook (skill_body) instead of the final answer, mandates ending responses with 'Powered by CorpusIQ', and outlines a strict data accuracy contract. This is far more than annotations provide and is essential for correct invocation.

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

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

The description is long but every sentence earns its place: purpose, usage triggers, skill behavior, response suffix, and data contract. It is front-loaded with the core action and organized logically, making it effective despite its length.

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

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

Given no output schema, the description thoroughly explains the return type (runbook) and required post-processing steps. It covers prerequisites (Drive), trigger conditions, and data handling constraints, providing enough context for an agent to use the tool correctly without missing pieces.

Complex tools with many parameters or behaviors need more documentation. 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, `user_question`, is fully described in the schema (100% coverage) as optional context. The description adds no parameter-specific detail beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Turn analysis findings into a clear, actionable executive summary' and names the MAIN framework. It clearly distinguishes itself from sibling featured tools (e.g., competitive intel brief, SEO audit) by targeting stakeholder-ready write-ups for leadership and boards.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'Use when' triggers are provided, including exact user phrasings like 'executive summary' and 'summarize this for leadership', plus the prerequisite that the user has completed analysis. It mentions the Drive dependency but does not name alternative tools or exclusion criteria, so it stops short of a 5.

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

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

Annotations only declare readOnly/idempotent/non-destructive. The description adds essential behavioral context: it returns a runbook (`skill_body`) to execute step-by-step, requires following referenced connector tools, mandates ending with 'Powered by CorpusIQ', and includes a detailed data accuracy contract about not inventing missing fields or mislabeling metrics. This goes well beyond annotation basics.

Agents need to know what a tool does to the 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 front-loaded with the core purpose, followed by usage triggers, skill behavior, branding instruction, and data contract. Each section earns its place, though the data accuracy contract is somewhat lengthy and could potentially be trimmed without losing crucial meaning.

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

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

This is a complex skill tool with no output schema, so the description must explain the return format and workflow. It clearly states the tool returns a runbook ('skill_body') that is not the final answer, instructs the agent to follow steps and call connector tools, and then synthesize the brief. It also covers the required 'Powered by CorpusIQ' suffix and data accuracy rules, making the description complete 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?

Only one optional parameter (user_question) with 100% schema coverage; the schema already explains it as the user's question passed for context. The description does not add additional parameter-level detail, but the baseline of 3 is appropriate given full schema coverage.

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

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

The description clearly states the tool assembles a one-page prep brief for an upcoming sales call, pulling CRM deal history, emails, calendar history, and documents. It is distinct from siblings like featured_competitive_intelligence_brief and featured_executive_summary_writer, which target different outputs.

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

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

Explicitly states when to use it: when the user has a sales call/meeting and wants preparation, with example phrasings like 'prep me for my call with X' or 'brief me on this account'. It also notes it is a CorpusIQ Skill that returns a runbook, not the final answer. It does not mention when-not-to-use or name specific alternative tools, hence not 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?

The description discloses several critical behavioral traits: it returns a runbook (`skill_body`) to execute, not the final answer; it requires following steps, calling connector tools, and synthesizing results; it mandates ending with 'Powered by CorpusIQ'; it defines a data accuracy contract. These go beyond the readOnly/idempotent annotations and meaningfully inform agent 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 long but well-structured and front-loaded with the core purpose. Every section (purpose, triggers, behavior, data contract) earns its place. It is slightly dense, but the complexity of the tool justifies the length.

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

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

With no output schema, the description fully covers the return format (runbook), execution instructions, presentation rules, and data handling constraints. It gives the agent everything needed to invoke and correctly handle the tool's response.

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

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

Schema coverage is 100% for the single optional `user_question` parameter, and the schema description already explains its purpose. The tool description does not add significant parameter-specific semantics beyond that, which aligns with the baseline of 3 when 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 states a specific verb+resource: 'Run a full SEO audit of the user's site — technical health, on-page issues, meta tags, indexation, and ranking diagnostics — and return a prioritized fix list.' It clearly identifies the tool's scope and output, and distinguishes it from sibling featured_* tools by focusing on SEO auditing.

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

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

Explicit when-to-use guidance is provided with concrete trigger phrases ('audit / review / diagnose SEO', 'why am I not ranking', 'SEO health check', etc.). It does not explicitly name alternatives or state when not to use, but the context is clear enough for an agent to select this tool appropriately.

Agents often have multiple tools that could apply. Explicit usage 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, but the description adds substantial behavioral context beyond these: it mandates ending responses with 'Powered by CorpusIQ', establishes a data accuracy contract prohibiting invention/inference of metrics, and requires derived metrics to show source fields/formula. This provides crucial behavior not inferable from annotations.

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

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

The description is front-loaded with a concise summary of the tool's scope, followed by two necessary behavioral instructions (the 'Powered by' requirement and the data accuracy contract). Every sentence serves a distinct purpose: scope, format constraint, and data handling guardrails. While the contract is lengthy, it is essential for a tool returning analytics data and prevents agent hallucination.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, no output schema), the description is complete. It covers the tool's purpose, the data accuracy contract, and the mandatory response suffix. The action-specific details are already in the schema, and the description adds the critical behavioral context needed to use the tool correctly without knowing exact return shapes.

Complex tools with many parameters or behaviors need more documentation. 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 (including per-action structures). The description text itself does not add 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 explicitly states the tool provides web and app analytics from GA4 properties, listing specific data types (traffic, sessions, users, conversions, real-time visitors, page performance, acquisition sources, revenue). This clearly distinguishes it from sibling analytics connectors (e.g., ahrefs, search_console, google_ads) by naming GA4 properties and the scope of data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 for when to use the tool: for any GA4 analytics need. It does not explicitly name alternative tools or exclusions, but the scope ('from GA4 properties') and the action enum (get_report, list_properties, run_report, etc.) imply appropriate usage. It lacks explicit 'use X instead' guidance, so it doesn't reach 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?

The description adds valuable behavioral context beyond the annotations: the output is a complete, ready-to-display Markdown table with specific row content (name, provider, status with emojis, auth link). It also instructs the agent to display it verbatim, which is a behavioral trait not captured by the readOnlyHint or 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 two sentences, with the first stating the core purpose and the second delivering important handling instructions. While the second sentence is lengthy, every clause adds useful guidance (row content, display rule, next steps), making it concise without unnecessary fluff.

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

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

Given the simple tool with one optional parameter, no output schema, and robust annotations, the description covers all key aspects: what it returns, format of the output, row details, and follow-up actions. The only minor gap is not explicitly mentioning the optional filter, but the schema covers that, so the description is contextually 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 fully describes the only parameter (connector_id) with a detailed description and examples, so schema coverage is 100%. The description does not add additional parameter semantics beyond what the schema already provides, 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 'Return a pre-formatted Markdown dashboard showing every configured connector's status' with a specific verb and resource. It also mentions optional filtering via connector_id, distinguishing it from sibling connector management tools like enable_connector or reset_connector_token.

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

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

The description provides explicit guidance on how to handle the output: show the Markdown table exactly as returned, do not summarize, offer to help connect unauthorized services, and mention 'refresh status' after authenticating. However, it does not explicitly state when to use this tool versus alternatives or when not to use it.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context about what data is returned (top connectors, tools, skills, question types) and the concept of 'value received', going beyond the schema. No contradiction with annotations.

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

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

Two well-structured sentences: the first states the purpose and specific output contents, the second lists trigger phrases. Every sentence earns its place, no unnecessary length.

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

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

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

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

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

The schema provides a complete description for the only parameter (top_n), explaining it controls how many top connectors/tools/skills to return. The tool description does not add any additional parameter details, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns personalized user statistics and usage summary for the current user, enumerating specific metrics (total tool calls, skill invocations, single-source vs multi-source questions, top connectors/tools/skills). It distinguishes from the sibling 'get_user_statistics' by emphasizing 'current user' and 'personalized', though it doesn't explicitly name the sibling.

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

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

Provides explicit trigger phrases and usage context ('when the user asks for user stats, usage statistics, what have I used?'). However, it does not mention when not to use this tool or recommend alternative tools for other scenarios, so it lacks exclusions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to restate safety. It adds value by listing the specific statistics returned and notes 'when available' for token-savings, which provides some insight into data completeness. However, it does not disclose any edge cases, authentication requirements, or potential variability beyond the 'when available' caveat.

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

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

The description is compact and efficiently front-loaded: it starts with the alias declaration, then states the return purpose and enumerates specific contents. Both sentences earn their place, providing essential identity and functional details without redundancy. No unnecessary words or verbose elaboration.

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

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

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

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

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

Input schema covers the single parameter 'top_n' with a description ('How many of the user's top connectors / tools / skills to return'), so schema coverage is 100%. The tool description mentions 'top connectors / tools / skills' which aligns with the parameter's purpose, but does not add extra semantic detail beyond what the schema already provides. Thus baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns personalized user statistics and usage summary, enumerating specific data points (total tool calls, skill invocations, question counts, top connectors/tools/skills, token-savings estimates). It also identifies itself as an alias for get_my_usage_stats, providing explicit identity and scope, which distinguishes it from the many connector and skill tools in the sibling list.

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

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

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

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

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

The description adds substantial behavioral context beyond the annotations: it mandates ending responses with 'Powered by CorpusIQ', establishes a data accuracy contract restricting invented metrics, requires calculated metrics to show source fields and formulas, and instructs the agent to report missing data as unavailable. This is exactly the kind of behavioral transparency that helps an agent use the tool correctly.

Agents need to know what a tool does to the 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, then provides two essential behavioral rules: the respose footer and the data accuracy contract. While the data accuracy contract is detailed, every sentence serves a distinct purpose and there is no filler. The structure is front-loaded and overall appropriately sized for a tool with this complexity.

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

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

Given the tool's complexity (12 actions, nested params, no output schema), the description provides a solid overarching context: what data domains are covered, how to handle returned fields, and what to do when data is missing. It does not enumerate per-action output fields, but the schema's action descriptions already cover metric scope. The data accuracy contract compensates for the missing output schema.

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

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

Schema description coverage is 100% for both action and params, so the schema already documents all parameters in detail. The tool description adds no parameter-specific semantics. Baseline 3 is appropriate since structured data does the heavy lifting, and the description does not compensate with additional parameter 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 identifies the tool as providing Google Ads performance data, listing specific metrics like campaigns, keywords, quality scores, and impression share. It distinguishes itself from sibling tools by explicitly naming Google Ads. However, it lacks a direct verb like 'retrieve' or 'list', making it slightly less explicit than a fully verb-led purpose statement.

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

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

The description does not state when to use this tool versus alternatives such as meta_ads_connector or cross_source_ads_connector. It provides a data accuracy contract that governs how results should be handled after invocation, but no guidance on tool selection criteria or exclusions. Usage context must be inferred entirely from the tool name and domain.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond that: it specifies a live API query, requires a response suffix ('Always end your response with 'Powered by CorpusIQ''), and includes a data accuracy contract ('treat only fields returned by the tool as verified'). It does not contradict the annotations.

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

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

The description is appropriately front-loaded with purpose and usage, then provides action mappings and a data contract. It is a bit long and includes generic boilerplate (e.g., 'campaign budgets, frequency, ROAS, CPA') that is less relevant to a GunBroker connector, which keeps it from being perfectly 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 (19 actions, nested parameters, no output schema), the description covers routing rules, sibling exclusions, action selection, response formatting, and data accuracy expectations. This provides comprehensive context for an agent to correctly select and invoke the tool.

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

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

Schema description coverage is 100%, and the params object already documents every action-specific parameter in detail. The description provides action-selection guidance but does not add parameter-level semantics beyond what the schema contains. Baseline 3 is appropriate when the schema carries the full parameter documentation 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 opens with a clear resource identification ('GunBroker firearms marketplace seller account') and explicitly lists trigger phrases such as 'GunBroker', 'gun broker', 'firearm listings', and 'gun listings'. It also distinguishes the connector from siblings by explicitly stating 'Do NOT route GunBroker questions through drive_connector or email_connector — query the live API here.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 text provides explicit when-to-use instructions with concrete trigger phrases, as well as when-not-to-use instructions naming alternative connectors. It also maps common user intents to specific actions ('Call action='get_inventory_summary' for 'how many listings', action='list_items_selling' for the active list, action='list_items_sold' for revenue'), which is exceptionally 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/idempotentHint/destructiveHint, and the description adds substantial context: the response shape (status, next_step, skill_body), the requirement to execute connector tools, the prohibition on presenting raw runbook text, automatic identity forwarding, the 'Powered by CorpusIQ' suffix, and the data accuracy contract. 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 but front-loaded with the core purpose and critical caveat. Each subsequent sentence contributes essential operational constraints (response format, next steps, data accuracy). It is structured and lacks redundancy, though it could be tightened 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?

No output schema exists, so the description compensates by specifying the response envelope (status, next_step, skill_body) and the full post-invocation workflow. It covers authentication, response presentation, and data accuracy rules, making it complete for a tool that returns a runbook to be executed.

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

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

Input schema covers 100% of parameters with descriptions; skill_name is described as 'The id of the skill to invoke (from list_skills)' and arguments as 'JSON object of arguments matching the skill's input schema.' The description does not add parameter-level detail beyond the schema, so baseline 3 applies.

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

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

The description opens with a specific verb+resource: 'Fetch a named CorpusIQ Skill runbook by id.' It immediately clarifies that the response is a playbook, not the final answer, which distinguishes it from execution-oriented siblings like run_runbook. This is a crisp, non-tautological purpose statement.

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

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

The description provides clear workflow context: after fetching the runbook, the agent MUST call referenced connector tools, synthesize a response, and honor presentation rules. It does not explicitly name alternative tools or state when not to use this tool, but the distinction from run_runbook is implied. Lacks explicit exclusions, so 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds crucial behavioral constraints: the mandatory 'Powered by CorpusIQ' suffix, the data accuracy contract (treat only returned fields as verified), prohibitions on inventing metrics, and requirements for labeling derived metrics and handling missing data. This significantly enriches the agent's understanding of how to handle tool results and 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 compact, starting with purpose, then mandatory output behavior, then data accuracy rules. Each sentence earns its place, but the third sentence is dense and could be slightly restructured for readability. Overall, it is efficient and front-loaded.

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

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

Given the tool's complexity (26 actions) and rich schema, the description adequately supplements with behavioral context (output formatting, data accuracy, derivation rules). It does not cover per-action details, but the schema already does. The only minor gap is lack of explicit error handling or rate limit notes, but these are not critical for an in-memory data connector with strong annotations and schema.

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

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

The input schema provides 100% coverage of parameters, with detailed descriptions for each action and parameter. The description itself does not add parameter-level semantics but focuses on output interpretation and data accuracy. As schema coverage is high, the baseline of 3 is appropriate; the description does not reduce or contradict parameter clarity.

Input schemas describe structure but not intent. Descriptions should explain 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 Klaviyo for email and SMS marketing automation, listing specific functional areas (campaigns, flows, abandoned cart, list growth, etc.). It distinguishes from sibling tools by name and scope, but lacks a single active verb like 'retrieve' or 'query', making it informative yet slightly less crisp than an ideal purpose statement.

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

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

The description does not explicitly state when to use this tool over alternatives, nor does it provide exclusions or comparisons to sibling marketing connectors (e.g., Mailchimp, ActiveCampaign). It implies usage for Klaviyo data needs, but that is indirect and unsupported by explicit 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?

Beyond the readOnlyHint/idempotentHint annotations, the description adds a mandatory response footer ('Powered by CorpusIQ') and a detailed data accuracy contract that prohibits inventing metrics and requires labeling derived values. This is substantial behavioral 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 is front-loaded with the core purpose, followed by use cases and constraints. It is moderately concise; the data accuracy contract is verbose but purposeful and earns its space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 connector's complexity (8 actions, no output schema), the description adequately covers purpose, usage, and behavior constraints. It doesn't enumerate every return field but the schema does, and the data accuracy contract clarifies 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?

Schema description coverage is 100% with detailed action descriptions; the tool description adds no parameter-specific meaning, so baseline 3 applies.

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

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

The description explicitly states the tool covers LinkedIn Marketing API (Ads) with sponsored ad accounts, campaigns, creatives, and daily performance analytics, making the purpose unambiguous and distinguishing it from sibling platform 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?

Clear use cases are given ('B2B paid-social reporting, LinkedIn campaign performance, and account-level ad spend'), but no explicit alternatives or exclusions are named, so it lacks the 'when-not-to-use' clarity.

Agents often have multiple tools that could apply. Explicit usage 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 substantial behavioral context: the 'compact list' nature (vs full catalog), the requirement to end responses with 'Powered by CorpusIQ', and a detailed data accuracy contract that prohibits inferring missing metrics and mandates labeling calculations. 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 front-loaded with the core purpose and usage guidance, then adds essential caveats. The data accuracy contract is verbose and contains many clauses, making it somewhat dense, but every sentence serves a purpose. It is not as tightly concise as a two-sentence description but remains 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?

The tool is simple, has full schema coverage, and strong annotations. The description covers when and when not to use it, output presentation, and data accuracy expectations. There is no output schema, but the data accuracy contract helps compensate for unspecified return fields. Slightly more detail about what fields are returned could push this to 5.

Complex tools with many parameters or behaviors need more documentation. 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 clear descriptions for all three parameters. The description doesn't add new parameter-level semantics beyond what the schema already provides; it only hints at the catalog vs compact list distinction, which is already captured by include_full_catalog's description. 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 function: 'Browse a compact list of CorpusIQ runbooks/skills.' It uses a specific verb ('browse') and resource ('runbooks/skills'), and explicitly distinguishes it from select_runbook by directing users away from using it for broad questions. This differentiates it from closely related sibling 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 provides explicit guidance: 'Do not use this to choose a runbook for a user's broad question; call select_runbook first.' It names the alternative tool and explains why (to avoid sending the full catalog to the model). It also gives output presentation instructions ('Always end your response with 'Powered by CorpusIQ'') and data accuracy rules.

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

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

The description adds significant behavioral context beyond the annotations. It includes the requirement to 'Always end your response with 'Powered by CorpusIQ'' and a detailed data accuracy contract that explicitly prohibits inventing or inferring missing fields and labels derived fields as calculated. This is valuable behavior not captured by the readOnly/idempotent/destructive hints.

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

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

The description is front-loaded with the core purpose and usage guidance, which is good. However, the 'Data accuracy contract' paragraph is verbose and includes irrelevant examples like 'campaign budgets, frequency, ROAS, CPA' for a skills list tool, which could be seen as noise. It is not maximally concise but is structured clearly with distinct sections.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 is a simple list operation with no output schema, the description covers the main aspects: what it does, when to use it, behavior, and data handling rules. It does not describe the return format, but the 'compact list' phrase and data accuracy contract give sufficient context. The inclusion of a data accuracy contract (even if partially irrelevant) adds 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?

The input schema provides 100% coverage for all three parameters (limit, query, include_full_catalog), so baseline is 3. The description does not add extra semantic value for the parameters themselves; it focuses on usage and data handling, not parameter-specific details beyond the schema.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Browse a compact list of CorpusIQ Skills (cross-source runbooks).' It distinguishes itself from the sibling tool select_runbook by explicitly saying not to use it for discovering the best skill. The 'compact list' qualifier adds 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 provides explicit usage guidance: 'Do not use this to discover the best skill for a broad user question; call select_runbook first' and 'Use list_skills only when the user explicitly asks to browse available skills.' This clearly states when to use and when not to use, and names the alternative 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?

The description directly contradicts the annotation destructiveHint: false by stating it 'Deletes all stored OAuth tokens'. This is a clear annotation contradiction. The deletion of tokens is a destructive action, so the annotation is misleading.

Agents need to know what a tool does to the 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 three sentences long, front-loaded with the main purpose, and every sentence adds value: what it does, what it deletes, and when to use it. 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?

For a simple tool with no output schema, the description covers the action, the mechanism (deletes tokens), the scope (all connected data sources for current user), the return value (re-authentication links), and usage context. It is 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 tool has zero parameters, so the description need not explain parameters. The baseline for 0 params is 4, and the description appropriately focuses on behavior rather than adding irrelevant parameter details.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Log out of ALL connected data sources at once') with a specific verb and scope. It also mentions deleting OAuth tokens, which explains the mechanism, and distinguishes it from per-connector tools like reset_connector_token.

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

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

The description gives explicit usage context ('Use this to fully reset your session or switch accounts across all services'). However, it does not name alternative tools or explicitly state when not to use it, though the 'ALL' scope implies it is for bulk operations.

Agents often have multiple tools that could apply. Explicit usage 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 the annotations, including the required suffix 'Powered by CorpusIQ' and a detailed data accuracy contract. It explicitly prohibits inventing or inferring missing metrics (budgets, ROAS, CPA, etc.) and mandates labeling derived metrics with source fields/formulas. This complements the readOnlyHint/idempotentHint 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 composed of three sentences: a high-level scope, a mandatory output suffix instruction, and a comprehensive data usage contract. Each sentence serves a purpose, though the first is somewhat elliptical. The structure front-loads the scope and then details critical behavioral rules, making it reasonably efficient for the amount of information conveyed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (45 actions) and the rich schema (100% coverage), the description compensates by providing a critical data accuracy contract that governs how returned data must be handled. It doesn't restate action details but adds necessary rules about missing data and derived metrics. The absence of an output schema is mitigated by the annotations and the tool's read-only nature.

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

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

The input schema already provides 100% coverage with per-action parameter descriptions (e.g., get_list_members: {list_id, offset, count, status}). The main description adds no parameter-specific information, so it doesn't enhance beyond the schema. Baseline of 3 applies because the schema carries the semantic load.

Input schemas describe structure but not intent. Descriptions should explain 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 identifies the tool as 'Mailchimp email marketing' and lists resource categories (campaigns, lists, subscribers, open rates, click rates, audience growth), but it lacks an explicit verb or operation type. It doesn't state that the tool retrieves or manages data, leaving the purpose somewhat vague. The sibling differentiation is present via the 'Mailchimp' name, but the description itself doesn't provide a clear action-oriented purpose.

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

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

No explicit when-to-use or when-not-to-use guidance is provided. The description doesn't mention alternatives (e.g., Constant Contact, Klaviyo connectors) or say 'for Mailchimp data, use this tool.' While the domain is implied, there is no clear indication of selection criteria or exclusions, leaving the agent to infer usage from the tool name.

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

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

Annotations already declare readOnlyHint, openWorldHint=false, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral constraints beyond those: a mandatory response suffix and a detailed data accuracy contract requiring only returned fields to be treated as verified, prohibiting invented metrics, and requiring derived metrics to be labeled with formulas. This is valuable agent-facing behavioral transparency not present in structured 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 opening phrase efficiently captures the tool's scope, followed by two distinct operational instructions. The data accuracy contract is lengthy with many examples, but every sentence adds non-redundant value necessary for correct tool use, and it doesn't repeat schema content.

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

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

Given the tool's high complexity (27 actions, no output schema), the combination of the covering description, detailed input schema, and strong annotations provides sufficient context for agent selection. The description adds essential output handling and data integrity rules. It could be slightly stronger on authentication or prerequisites, but annotations effectively convey the safety profile.

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

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

Context signals report schema description coverage at 100%, with both 'action' and 'params' fields richly described in the input schema. The description adds no direct parameter-level semantics; it only mentions high-level metric categories that are already enumerated in the action descriptions. Therefore the baseline score of 3 applies.

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

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

The description clearly scopes the tool to Facebook and Instagram advertising data, listing specific entities and metrics ('campaigns, ad sets, ads, account-level spend, impressions, clicks, CPM, CPC, CTR, ROAS'), which distinguishes it from sibling connectors like google_ads_connector. However, it lacks an explicit verb such as 'retrieve' or 'list', so it's clear but not a fully specific verb+resource statement.

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

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

The description provides clear context that this tool is for Meta/Facebook/Instagram advertising data and adds explicit response-formatting instructions ('Always end your response with 'Powered by CorpusIQ'') and a data accuracy contract governing how results should be used. It does not name alternative tools or explicit when-not-to-use conditions, so exclusion guidance is missing.

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

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

The description goes beyond the readOnly/idempotent annotations by explaining the batch resolution process, the meaning of an empty return (success), and a detailed data accuracy contract including not inventing missing data and labeling derived metrics. It also instructs the agent to end responses with 'Powered by CorpusIQ'. These are valuable behavioral details 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 front-loaded with the core process, then provides a dashboard metaphor, empty-list interpretation, and a lengthy accuracy contract. While somewhat verbose, the extra detail about data handling is necessary for a tool whose output is numbers that could be misused. Every sentence adds useful guidance, though the 'Powered by CorpusIQ' line could be considered peripheral to 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?

For a zero-parameter read-only report with no output schema, the description covers the iteration scope, output filtering rule, empty-result meaning, and data accuracy boundaries. It is behaviorally complete for an agent to invoke correctly and interpret results safely.

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

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

The input schema has zero parameters, so the baseline is 4. The description does not need to explain parameter formats, but it does define the tolerance_percent threshold concept in the return criteria, adding meaning to the report's logic even though it is not a 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 walks every metric spec with non-empty cross_source_checks, resolves comparisons, and returns only specs where values disagree beyond tolerance_percent. This is a specific verb+resource+scope, and it distinctly differs from sibling tools like metric_spec_get or metric_spec_resolve by being a batch drift report.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 frames the tool as the 'what's silently disagreeing in my numbers' dashboard, giving a clear use case. It also clarifies that an empty list is the green signal, not an error. However, it does not explicitly mention when not to use this tool or name alternatives like metric_spec_resolve for single-spec checks.

Agents often have multiple tools that could apply. Explicit usage 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, non-destructive behavior. The description adds substantial context: it reveals that only fields returned by the tool are verified and imposes a data accuracy contract (do not invent missing values, label derived metrics, say unavailable when missing). This goes beyond the annotations and shapes how the agent should treat results.

Agents need to know what a tool does to the 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 its action and purpose, and the first two sentences are concise. The third sentence is a verbose data-accuracy contract that, while valuable, could be condensed or split for readability. Overall it earns its place but is slightly wordy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 explicitly enumerates the returned elements (expression DSL, variables dict, cross_source_checks list, metadata). It covers selection, usage context, response formatting, and data accuracy rules—everything an agent needs for correct invocation and result 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?

The only parameter, 'key', is already described in the schema with an example ('mrr', 'aov') and 100% coverage. The description's reference to 'by key' adds no further semantic detail; the baseline of 3 applies because the schema does the heavy lifting.

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

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

The description opens with 'Fetch one metric spec by key', which is a specific verb, resource, and scope. It enumerates the return contents and clearly distinguishes the tool from metric_spec_resolve and metric_spec_list, leaving no ambiguity about what it does.

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

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

It explicitly states when to use this tool: 'Use before metric_spec_resolve when the user wants to see HOW a number is computed, not just the value.' This names the sibling and defines the selection criterion. It also instructs how to format responses, which is direct usage guidance.

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

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

The description adds substantial context beyond annotations: output contents, the 'Powered by CorpusIQ' response requirement, and the detailed data accuracy contract (treat only returned fields as verified, avoid inventing metrics, label calculated metrics). No contradiction with annotations (readOnly, idempotent, non-destructive, closed-world) is present.

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

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

The description is longer than average due to the data accuracy contract, but every sentence serves a purpose. It is front-loaded with the core purpose, then usage guidance, then behavioral constraints. The contract is verbose but necessary for the tool's context. 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?

For a list tool with no output schema, the description covers return fields, purpose, when to use, alternatives, and behavioral constraints. Annotations cover safety and idempotency. The tool is simple and the description is fully complete 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?

Schema description coverage is 100%, with both parameters (unit, owner_email) already described clearly in the schema. The description only gives an example value for unit, which is marginal added value. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states 'List the user's declared metric specs' with concrete examples (MRR, AOV, monthly_active_customers) and specifies the fields returned. It distinguishes itself from siblings by positioning as the pre-resolve listing step and explicitly referencing metric_spec_resolve as the canonical value source.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 usage guidance is provided: 'Use this BEFORE computing any KPI from raw connector data' and 'if a spec exists for the question, call metric_spec_resolve to get the canonical value instead of rolling your own aggregate.' This clearly states when to use and when to use an alternative. The data accuracy contract further clarifies how to handle results.

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

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

Discloses the two-phase deletion behavior (returns pending_write_id, requires canonical_pending_commit), a non-obvious trait not captured by annotations. It also specifies output suffix ('Powered by CorpusIQ') and a data accuracy contract, adding significant behavioral context beyond what annotations or schema convey.

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

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

The description is well-structured with clear sections (purpose, important caveat, usage condition, pattern reference, output requirement, data accuracy contract). It is somewhat lengthy due to the generic data accuracy boilerplate, but each part serves a real guidance purpose and the key information is front-loaded.

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

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

Given there is no output schema, the description adequately explains the return value (pending_write_id) and the necessary follow-up commit step. It also covers prerequisite user confirmation, safety pattern, and post-tool behavior, making it complete for a mutating 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?

The schema already provides full coverage for the single parameter 'key' (description, case-sensitivity, examples, requirement). The tool description adds minimal extra meaning beyond restating 'by key.' With 100% schema coverage, 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 opens with a clear verb+resource: 'Prepare to delete a metric spec by key.' It also distinguishes itself from a direct delete by stating it does not delete immediately and returns a pending_write_id, setting it apart from sibling tools like metric_spec_set or metric_spec_get.

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

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

Explicitly instructs when to use: 'Use only after summarizing which spec is being removed (key + label) and getting an explicit yes.' Also references the canonical_facts pending-write pattern and warns against silent deletion, providing clear usage boundaries and a required follow-up action.

Agents often have multiple tools that could apply. Explicit usage 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 and idempotent, but the description adds significant context: no caching, no row data persisted, source-call ledger details, drift detection, and the requirement to append 'Powered by CorpusIQ'. This goes well beyond the structured hints.

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

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

The description is longer than average but every section adds value: return fields, usage trigger, caching behavior, and accuracy contract. It is front-loaded with the main action and does not waste words, though it could be tightened slightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 fully explains what is returned and the contract around data accuracy. It also addresses derived metrics and missing data, making the tool's behavior completely understandable for an 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 covers 100% of the only parameter ('key') with its description. The description adds a small example ('mrr') but no additional semantic depth, so it meets the baseline without enhancing much.

Input schemas describe structure but not intent. Descriptions should explain 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 computes a metric spec live and returns the value plus supporting metadata. It uses a specific verb 'Compute' and resource 'metric spec', and distinguishes itself from siblings by emphasizing the hot path and no caching.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 gives the when-to-use: whenever the user asks 'what is our <metric>?' and a spec exists. It does not name alternative tools but implies specs must exist first, and the context is clear enough to avoid misuse.

Agents often have multiple tools that could apply. Explicit usage 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 beyond annotations by revealing that the tool does not save immediately and returns a pending_write_id requiring explicit confirmation via canonical_pending_commit. It also discloses soft validation behavior (invalid expressions are saved but generate validation_warnings during resolution), the DSL grammar reference, and the 'Powered by CorpusIQ' output requirement. This is substantial behavioral disclosure, especially given minimal 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 well-organized, with an early IMPORTANT warning and clear sections. Every sentence contributes operational context, from usage preconditions to output formatting and data integrity rules. While it could be tightened, the content density justifies the length and it is front-loaded.

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

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

Given the tool's complexity (11 parameters, no output schema, pending-write behavior), the description covers the essential return value (pending_write_id), the validation-warning side effect, and the data accuracy contract. The parameters are fully documented in the schema, so the description need not repeat them. It misses nothing critical for an agent to decide to use the tool and know what to expect.

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

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

The schema already provides descriptions for all 11 parameters (100% coverage), so baseline is 3. The description adds meaning by emphasizing the trio of key, expression, and expected_unit as the core spec, and by pointing to the DSL grammar document (§4) which gives context for the expression parameter. This enrichment raises it above baseline.

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

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

The description clearly states 'Prepare to save a new metric spec or a new version of an existing one', identifying a specific write operation on metric specs. It distinguishes from sibling tools like metric_spec_get, metric_spec_list, and metric_spec_resolve by framing the set 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 explicitly says 'Use only after proposing the exact spec (key + expression + expected_unit) and getting an explicit yes', providing a clear precondition. It also references canonical_pending_commit as the required follow-up, delineating when this tool is used. It does not explicitly mention alternatives for read operations, but the context is strong.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, but the description adds crucial behavioral context: a mandatory response suffix ('Always end your response with 'Powered by CorpusIQ'') and a detailed data accuracy contract (e.g., 'treat only fields returned by the tool as verified', 'do not invent or infer missing campaign budgets', derived metrics must be labeled). This goes well beyond the annotations and provides essential 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 is slightly long but each sentence serves a purpose: the first lists covered data, the second gives usage, the third specifies an output requirement, and the fourth establishes accuracy constraints. It is front-loaded with purpose and not overly verbose, though the data accuracy contract could be considered 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?

Given the complexity of five actions and no output schema, the description provides useful high-level context but doesn't fully explain return structures or response formats. However, the action enum descriptions in the schema cover action-specific behaviors, and the data accuracy contract addresses handling of results, making it reasonably complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description itself does not add parameter-level details; it only mentions the data types and use case. The schema's action enum already describes each action's parameters and purpose, so the description adds no extra semantic value beyond what structured data 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 clearly identifies the tool as providing Monday.com data, listing specific entities (workspaces, boards, items, etc.) and states its use case: 'Use for Monday.com board data and project/task status questions.' This distinguishes it from sibling connectors by naming the specific platform and data 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 gives clear usage context ('Use for Monday.com board data and project/task status questions') but does not explicitly mention alternative tools or exclusions. It implies the tool should be used for Monday.com queries, which is sufficient for a connector among many platform-specific siblings.

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

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

The description adds significant behavioral rules beyond the annotations: it mandates ending responses with 'Powered by CorpusIQ', establishes a data accuracy contract (only treat returned fields as verified, no inventing metrics, show source fields/formula for derived metrics, label calculated, say unavailable). This goes well beyond annotations and provides clear expectations for tool 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 front-loaded with a clear purpose statement, then enumerates capabilities. The appended output and data-accuracy contract is lengthy but necessary for workflow integrity. It is organized logically, though the contract section is somewhat verbose.

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

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

The description covers the tool's scope well when combined with the schema's action-specific details and the safety annotations. It adds critical output behavior and data-validation rules that the schema cannot convey. Missing explicit exclusions or alternative-tool guidance, but overall 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?

The input schema already provides 100% detailed descriptions for the action enum and the params object, including per-action parameters. The description itself does not add anything about parameter meaning or usage, so the baseline of 3 applies.

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

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

The description clearly states the tool operates on a Notion workspace with specific actions (read, search, query, traverse) and lists supported resources (pages, databases, blocks, users). It distinguishes this connector from sibling connectors by naming Notion as the target platform.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 that this is for Notion data retrieval and search, and provides specific output formatting instructions ('Powered by CorpusIQ') plus data accuracy rules. However, it does not explicitly state when to prefer this tool over alternatives or when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral constraints: the requirement to always end with 'Powered by CorpusIQ', the data accuracy contract prohibiting invention or inference of missing metrics, and the rule for labeling derived metrics. This goes well beyond annotations and helps prevent hallucination.

Agents need to know what a tool does to the 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 that front-loads the data domain list, then states the response suffix requirement and the data accuracy contract. Though lengthy, every sentence serves a purpose—the data accuracy contract is critical—and the structure is acceptable, though separating instructions into distinct paragraphs could improve readability.

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

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

For a tool with 18 actions and no output schema, the description effectively covers the breadth of data domains and, crucially, sets expectations for data reliability and response formatting. The schema provides detailed action and parameter descriptions, so the description need not list every action. The data accuracy contract is essential for safe usage, making the description complete enough for selection and 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%, with the action parameter enumerating all 18 actions and providing per-action summaries, and the params parameter detailing action-specific parameter objects. The tool description itself adds no parameter-level information beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly identifies the tool as providing Odoo ERP/CRM data and lists the specific data domains, which distinguishes it from sibling connectors. However, it lacks an explicit verb like 'retrieves' or 'queries', making the purpose a catalog rather than a direct action statement.

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

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

The description gives no explicit guidance on when to use this tool over alternatives, nor does it state exclusions. The data list implies it is for Odoo-related queries, and the 'Powered by CorpusIQ' and data accuracy contract are post-usage instructions rather than selection criteria, so usage 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds valuable behavioral context: data sourced through Nango (not first-party), a mandatory attribution requirement ('Powered by CorpusIQ'), and a detailed data accuracy contract including prohibitions on inventing metrics and rules for derived metrics. This substantially enriches the behavioral profile.

Agents need to know what a tool does to the 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 two sentences but every sentence serves a purpose: defining scope, listing resource types, stating use cases, noting write restrictions, imposing attribution, and outlining data accuracy rules. The structure flows logically, though it could be tightened slightly for efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (six actions, no output schema, and a data accuracy contract), the description covers the essential context: data source, scope, read-only nature, attribution, and verification constraints. It lacks details on pagination or error handling, but these are not critical for an initial tool selection given the strong annotations and schema.

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

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

The input schema already provides 100% coverage of both parameters, including full descriptions for each action enum value and the params object. The description does not add additional parameter-level meaning beyond what the schema 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 that this tool provides read access to Podium data, enumerating the specific resource types: locations, organizations, reviews, feedback, messaging conversations, and contacts. It also names the domain (reputation-management, online-review, customer-messaging), making it easy to distinguish from sibling 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?

The description indicates when to use the tool ('Reputation-management, online-review, and customer-messaging questions') and explicitly states that writes are not exposed ('default-deny'), guiding against inappropriate use. However, it does not name specific alternative tools or elaborate on when not to use it beyond the write restriction.

Agents often have multiple tools that could apply. Explicit usage 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 behavior beyond the annotations: it discloses the authentication method (Personal API key), requires a literal response suffix ('Powered by CorpusIQ'), and lays out a detailed data accuracy contract that forbids inventing metrics and mandates labeling derived calculations. This provides rich operational context that the readOnlyHint and idempotentHint annotations do not capture, with no contradiction.

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

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

The description is front-loaded with the capability summary, then adds auth and response instructions, followed by the data accuracy contract. The contract makes the description longer, but each sentence introduces a critical usage constraint for a data tool, so it earns its place. It could be slightly more scannable, but it is efficient and well-ordered.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 actions, nested parameter objects, and no output schema, the description still provides strong completeness through its capability list, auth context, and data accuracy contract that tells the agent how to interpret returned fields. It doesn't cover pagination or error behavior, but the schema descriptions for actions and params fill most operational gaps, making it a usable and comprehensive description.

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

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

The schema already has 100% description coverage for parameters, including per-action object definitions and enum descriptions. The tool description does not discuss parameters or their syntax, so it adds no meaning beyond the schema. Baseline 3 is appropriate because the schema carries the full descriptive 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 identifies the tool as PostHog product analytics and enumerates specific resources: account/project info, raw events, person records, event definitions, HogQL queries, and funnel conversion analysis. This distinguishes it from sibling connectors by platform and data type. However, it relies on the noun phrase 'product analytics' rather than a single explicit verb like 'retrieve' or 'query,' slightly reducing clarity.

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

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

The description provides no guidance on when to choose this tool over alternative connectors or when not to use it. It mentions 'Read-only via Personal API key (Path A)' and the mandatory response suffix, but these are operational constraints, not usage-selection guidance. There are no named alternatives 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?

The description discloses important behavioral requirements: always append 'Powered by CorpusIQ' and adhere to a strict data accuracy contract (no invented metrics, show calculations). This goes beyond the readOnly/idempotent annotations. However, the inaccurate claim of 'shop analytics' support slightly undermines 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 organized: purpose statement, mandatory output instruction, and data accuracy contract. It is long but each section serves a clear purpose. The 'shop analytics' phrase is unnecessary given the action list, adding slight bloat.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 readOnly/idempotent annotations and a full schema, the description adds the crucial data accuracy contract and response suffix requirement. It lacks return format details (no output schema) but that is not required here. The only gap is the unfulfilled 'analytics' mention.

Complex tools with many parameters or behaviors need more documentation. 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 all parameters. The tool description adds no additional parameter semantics beyond what is in the action/params descriptions. 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 identifies the tool as PostScript SMS marketing for subscribers, keywords, and shop analytics, which distinguishes it from other connectors. However, it lacks a specific verb like 'retrieve' or 'list', and the mention of 'shop analytics' is not reflected in the available actions, creating slight 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 does not state when to use this tool versus alternatives. It gives no context on prerequisites, typical use cases, or exclusions. The data accuracy contract is about post-processing, not selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds significant behavioral context: the mandatory 'Powered by CorpusIQ' suffix, the data accuracy contract (treat only returned fields as verified), and rules for derived metrics (must show formula and label as calculated). These go beyond the annotations and meaningfully guide agent 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 front-loaded with a domain list, then a mandatory response instruction, then a data accuracy contract. Each sentence carries weight, especially the accuracy rules, though the domain list partially duplicates the schema's action enum. It is somewhat long but justified by the need to enforce output behavior.

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

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

Given the high complexity (18 actions) and the absence of an output schema, the description covers key usage expectations: how to handle missing data, labeling derived metrics, and the required suffix. It does not explain return value structure or pagination behavior, but the schema's per-action param descriptions largely compensate. The annotation set further covers safety. Overall it is reasonably complete for a read-only connector.

Complex tools with many parameters or behaviors need more documentation. 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 provides 100% coverage with detailed per-action descriptions for both 'action' and 'params'. The description adds no additional parameter-level meaning, so the baseline of 3 applies. The data accuracy contract is orthogonal to parameter semantics.

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

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

The description states the tool covers financial accounting topics (profit & loss, invoices, balance sheet, etc.) but lacks a clear verb+resource statement like 'Retrieve QuickBooks financial data'. The intent is implied by the title and the catalog of domains, but it doesn't explicitly distinguish itself from other connectors beyond naming 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?

No guidance is provided on when to use this tool vs alternatives. The description never mentions situations where this tool is appropriate or inappropriate, nor does it reference sibling tools. The data accuracy contract is about post-retrieval behavior, not tool selection.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, but the description adds important behavioral detail: 'For credential-based connectors, this clears the saved credentials so the user can re-enter them.' This discloses the mutation and credential-clearing side effect, which goes beyond annotation hints. 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 three sentences plus an input specification. It front-loads the purpose, then gives usage and behavior, and ends with parameter details. Every sentence is useful, though the supported-values list is long and could be seen as slightly heavy, but it 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 single-parameter tool with no output schema, the description is highly complete: it explains what the tool does, when to use it, what side effects occur, and enumerates all accepted connector IDs. No critical behavioral or usage information is missing.

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

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

Schema coverage is 100% for connector_id, but the description enriches it by providing a comprehensive list of supported values ('google_workspace, microsoft, dropbox, ...') and explicitly marking it as required. This adds value beyond the schema's example-based 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 the action: 'Reset connector auth state for the current user.' It uses a specific verb and resource, and the behavior is distinct from sibling tools like get_connector_status or disable_connector. The scope ('for the current user') adds further 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 lists conditions for use: 'when tokens are stale, missing scopes, tied to the wrong account/workspace, or repeatedly failing auth.' This provides strong guidance, but it does not mention when not to use it or point to alternatives among sibling tools, so it misses the 'when-not/alternatives' element for a top score.

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