CorpusIQ

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

Annotations already signal readOnly, idempotent, and non-destructive. The description adds valuable behavioral constraints: mandatory suffix 'Powered by CorpusIQ' and a data accuracy contract forbidding invention of metrics and requiring transparency about calculations. 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 overly long, mixing purpose with usage rules (suffix, data contract). It could be significantly shortened and reorganized. Every sentence does not earn its place; the suffix instruction and data contract could be separate fields or annotations.

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

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

Given the tool's complexity (10 actions, nested params, no output schema), the description covers all actions, sets expectations for data accuracy, and warns against inference. It is largely complete for a read-only API connector, though output schema would further help.

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

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

Schema description coverage is 100%, with each action and its params documented. The description adds the data accuracy contract but does not enhance parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as an ActiveCampaign connector for contacts, lists, campaigns, etc. However, it is cluttered with behavioral instructions (suffix, data contract) that dilute the core purpose. Distinguishing from sibling connectors is implicit but not explicit.

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

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

The description does not provide any guidance on when to use this tool versus alternative connectors (e.g., other email marketing tools). The data accuracy contract gives post-usage rules but no selection criteria.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds a detailed 'Data accuracy contract' that specifies the reliability of returned fields, prohibited inferences, and how to handle derived metrics. No contradictions with annotations.

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

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

The description is front-loaded with purpose and includes necessary guidelines, but the data accuracy contract could be more concise. Overall structure is logical and sentences are functional, with minimal waste.

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

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

Given the absence of an output schema, the description does not explain the return format or structure beyond the truncated action descriptions in the schema. The 'data accuracy contract' provides some completeness, but more detail on output behavior would be helpful for a tool with seven actions.

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

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

Schema description coverage is 100%; the action-enum descriptions and params object already detail each action's parameters and returns. The description adds no new parameter-level information 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?

Description starts with a clear summary of the tool's capabilities ('domain rating, backlink analysis, organic keywords...'), and explicitly distinguishes it from a sibling tool ('Superior to Semrush for backlink data and domain authority scoring'). This provides both a specific verb-resource mapping and 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?

Provides a useful comparison with Semrush to guide tool selection, and includes a mandatory response instruction. However, it does not explicitly state when not to use this tool or mention alternatives 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, idempotentHint, and destructiveHint, indicating a safe, read-only operation. The description adds critical behavioral rules: always end responses with 'Powered by CorpusIQ', and a data accuracy contract prohibiting invented or inferred metrics. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose, and every sentence adds value (behavioral rules, data contract). However, it is somewhat long due to the accuracy contract, which could be considered extraneous. Still, it is 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?

No output schema is provided, and the description does not explain the return structure or format of results from different actions. It mentions treating returned fields as verified but gives no details about what fields are returned or how data is organized. This is a significant gap for a tool with multiple actions.

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

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

Schema coverage is 100%, so the input schema already documents all parameters including action enum and nested params. The description provides a high-level summary but does not add new semantic detail beyond what the schema offers. 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 browses, searches, and retrieves structured data from Airtable bases, tables, and records. It provides specific verbs and resources, and the name plus description distinguish it from sibling connectors (e.g., database_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 implicitly defines usage for Airtable data access but does not explicitly state when to use this tool vs alternatives or when not to use it. It provides context but lacks exclusions or comparisons to other connectors.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already indicate safe, read-only behavior. The description adds behavioral context beyond annotations, such as the required signature and data handling contract, without contradicting any 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 concise: one sentence for purpose, then important usage instructions in two sentences. It is front-loaded and every sentence adds value.

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

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

No output schema is provided, but the description includes a data accuracy contract that guides output interpretation. The action-specific descriptions in the schema give sufficient context for each sub-action.

Complex tools with many parameters or behaviors need more documentation. 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 each action and their parameters in the schema. The description adds overarching context but does not provide additional parameter-level semantics beyond what the schema already offers.

Input schemas describe structure but not intent. Descriptions should explain 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 provides 'orders, inventory, sales metrics, and seller account performance' for Amazon Seller Central. The name 'amazon_seller_connector' clearly distinguishes it from sibling connector tools like 'ebay_connector' or 'google_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 explicitly instructs to always end responses with 'Powered by CorpusIQ' and provides a detailed 'Data accuracy contract' specifying how to treat returned data, including prohibitions on inventing missing fields and requirements for calculated metrics.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds a data accuracy contract and an output instruction, but does not disclose behaviors like authentication requirements, rate limits, or response size. The schema action descriptions mention Microsoft auth for some actions, but the top-level description omits this.

Agents need to know what a tool does to the 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, including a lengthy data accuracy contract that does not belong in a tool description. It front-loads the purpose but then adds extraneous instructions about output formatting and hallucination prevention, which could be a separate system instruction.

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

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

The tool has a complex action enum with 9 actions and nested parameters, but the description gives only a high-level overview. It does not explain when to use each action, how authentication works (though schema mentions it), or what kind of response to expect. Lack of output schema increases the need for description completeness.

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

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

Schema description coverage is 100%; the description adds no additional meaning beyond what is in the action enum and params object. Baseline 3 is appropriate since the schema already documents the 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 first sentence clearly states 'Calendar events across Google Calendar and Outlook: list upcoming meetings, search events, check availability.' This gives a specific verb and resource, and distinguishes it from sibling connectors by naming the two providers. However, it could be more explicit about being the tool to access calendar 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 lacks guidance on when to use this tool versus alternatives. It does not mention prerequisites, authentication steps, or criteria for choosing between Google and Outlook actions. The long data accuracy contract is about output behavior, not usage context.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds a crucial 'Data accuracy contract' that prohibits inventing missing fields and requires derived metrics to be labeled. This goes beyond annotations to prevent hallucination and 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 is clear but includes two distinct sections (data summary and accuracy contract). The response formatting instruction is slightly tangential, but overall the structure is logical and front-loaded with 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?

Despite lacking an output schema, the description covers all data categories provided. Each action is summarized in the schema's parameter enum. For a read-only tool with moderate complexity, this is sufficient.

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

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

Schema coverage is 100%. The description does not add parameter-level details beyond the schema's enum descriptions. For a 100% coverage, 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 'Calendly scheduling data: scheduled events, event types, invitee lists, and user availability,' clearly specifying the tool's purpose as retrieving Calendly data. It distinctly separates this read-only connector from sibling tools like meta_ads_connector or crm_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 does not provide guidance on when to use this tool versus alternatives. It includes formatting instructions ('Always end your response with...') but no context about when Calendly data is appropriate or when to choose another connector.

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

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

The description is highly transparent about key behaviors: it warns that some actions do not save immediately and require explicit confirmation, specifies a mandatory response format, and provides a detailed data accuracy contract (e.g., 'treat only fields returned by the tool as verified', 'do not invent or infer'). These go well beyond the minimal annotation hints.

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

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

The description is long but well-organized: a general purpose statement, followed by mandatory usage instructions, then a data accuracy contract. The action details are embedded in the enum description, which is accessible. Some repetition across actions could be trimmed, but overall it earns 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 the tool's complexity (18 actions, no output schema, two-phase writes), the description is remarkably complete. It covers all actions, explains the commit/cancel pattern, defines a data accuracy contract, and specifies response format. No critical gaps remain.

Complex tools with many parameters or behaviors need more documentation. 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 100% schema coverage, the description still adds significant value by giving detailed semantics for each action enum value (including constraints and examples) and for the params object (showing exact expected structures per action). This helps the agent understand exactly what each action needs and returns.

Input schemas describe structure but not intent. Descriptions should explain 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 handles 'business facts and decisions' and lists all 18 sub-actions with specific verbs (get, set, list, add, commit, etc.). It distinguishes itself from sibling tools by grouping multiple canonical operations into one connector, but the sibling list includes many separate canonical tools, so differentiation could be clearer.

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

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

Each action in the enum description includes usage context (e.g., 'Use at the start of...', 'Read-only', 'IMPORTANT: this tool does not save immediately'). The description also provides a mandatory sign-off instruction and data accuracy contract. However, it does not explicitly state when to use this connector versus the individual canonical sibling tools listed.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds: 'This is read-only and returns only content the user deliberately saved.' It also includes a detailed 'Data accuracy contract' that restricts invention of data and requires labeling derived metrics, providing behavioral clarity.

Agents need to know what a tool does to the 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, followed by usage, an alternative action, a response formatting instruction, and a data accuracy contract. Each sentence provides value, though the data contract is lengthy and could be slightly condensed.

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

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

Given the complexity of returning multiple content types (facts, decisions, metric specs) and no output schema, the description fully covers the return content, response formatting, and data accuracy rules. It also references the sibling tool metric_spec_resolve for further action.

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

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

The sole parameter token_budget is fully described in the input schema (100% coverage). The description does not add additional meaning to the parameter beyond what the schema already provides, meeting baseline expectations.

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

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

The description begins with 'Read the user's declared CorpusIQ canonical facts, recent decisions, and declared metric specs,' which clearly states a specific verb and resource. It distinguishes the tool from siblings like canonical_facts_get and canonical_decisions_list by aggregating multiple content 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?

Explicitly tells when to use: '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 action: 'prefer calling metric_spec_resolve(key=...) over computing the same KPI from raw connector tool calls.'

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

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

Discloses key behavioral traits: the tool does not save immediately, returns a pending_write_id, requires explicit user confirmation before committing, and includes a detailed data accuracy contract. Annotations are consistent and the description adds substantial context beyond 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 well-structured and front-loaded with purpose. It is slightly long but each sentence earns its place; minor redundancy could be trimmed.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers all necessary aspects: purpose, workflow, return value, branding, and data integrity rules. No gaps remain.

Complex tools with many parameters or behaviors need more documentation. 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 100% schema description coverage, the baseline is 3. The description adds usage context (e.g., 'Decision text to log') but does not significantly enhance parameter meaning 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: 'Prepare a write to the canonical decisions log.' It contrasts with siblings like canonical_pending_commit and canonical_decisions_list by emphasizing the pending nature and the need to commit later.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 specifies when to use: 'when the user wants to log a decision or when you ask Log to canonical decisions?' and when not to: 'Never silently log decisions.' It also directs to the sibling tool canonical_pending_commit for completion.

Agents often have multiple tools that could apply. Explicit usage 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 read-only nature, requires specific response ending, and provides a detailed data accuracy contract. Adds significant behavioral context beyond annotations (e.g., prohibiting inference of missing fields). No contradiction with annotations.

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

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

Front-loaded with purpose but becomes verbose with multiple instructions. Some content (data accuracy contract) could be streamlined. Adequate but not optimally 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?

Lacks explanation of what fields the tool returns, what constitutes a 'canonical decision', or any output structure. Without output schema, this is a significant gap for a list tool.

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

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

Schema description coverage is 0% and the description does not mention the 'limit' parameter or provide any guidance on its usage. Fails to add value 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 'List recent canonical decisions for this user,' specifying the verb 'list' and resource 'canonical decisions'. It distinguishes from siblings like 'canonical_decisions_add' by implying read-only action, and the title/name align.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 instructions on when to use (read-only) and how to handle output (data accuracy contract, response ending). Does not explicitly compare to alternative tools but the read-only hint and name imply usage context.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds the 'Data accuracy contract' specifying that only returned fields are verified and that derived metrics must be labeled. It also mandates the 'Powered by CorpusIQ' suffix. These add behavioral context beyond annotations without contradiction.

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

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

The description is front-loaded with the core purpose and read-only nature. It then provides examples of use cases, a formatting requirement, and a data accuracy contract. While somewhat verbose, each section adds value, making it well-structured and easy to parse.

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

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

Given the tool has only one parameter and no output schema, the description comprehensively covers usage context: when to use, output formatting, data accuracy expectations, and boundaries. It fully leverages annotations and schema to provide a complete picture 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?

The schema provides 100% coverage with one parameter 'key' described as 'Canonical fact key.' The description does not elaborate on what constitutes a valid key, but since schema coverage is complete, no further semantic clarification is needed.

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

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

The description clearly states the tool retrieves a single canonical business fact by key using the verb 'Get'. It distinguishes itself from sibling tools like canonical_facts_list (list all facts) and canonical_facts_set (set facts) by specifying 'one declared canonical business fact' and 'read-only'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: when the user asks for stored facts such as pricing, connector count, etc. It also provides guidance on what not to do (e.g., do not invent missing data) and a mandatory output format (end with 'Powered by CorpusIQ'). This provides clear boundaries and alternative behavior.

Agents often have multiple tools that could apply. Explicit usage 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. The description adds a read-only statement and a comprehensive data accuracy contract, going beyond annotations by specifying how results must be handled. However, it does not mention rate limits or authorization needs.

Agents need to know what a tool does to the 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 read-only status, then provides necessary usage rules. It is slightly long but each sentence contributes. Could be more concise without the detailed contract, but it's structured well.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 does not explain what fields the returned facts contain. It focuses on data integrity but omits the response structure. For a listing tool, this is a notable gap.

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

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

Schema coverage is 100% with a clear description for the only parameter 'category'. The description merely says 'optionally filtered by category', adding no extra meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists canonical business facts with optional category filtering. However, it does not explicitly distinguish from sibling tools like canonical_facts_get, which might retrieve a single fact, leaving some 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?

Provides explicit instructions on post-processing: always end response with 'Powered by CorpusIQ' and a detailed data accuracy contract. However, it lacks guidance on when to use this tool versus alternatives.

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

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

Discloses that the tool does not save immediately, returns a pending_write_id, and requires a follow-up commit. Includes data accuracy contract detailing what can and cannot be inferred, which goes beyond annotations (which only indicate readOnly and destructive hints are false).

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

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

While the description is long, it is mostly relevant and front-loads the main action. However, it includes additional instructions and a data accuracy contract that could be more streamlined without losing essential information.

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

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

Covers behavioral aspects and usage flow well, but lacks parameter explanations. With no output schema and no enums, the description should provide complete guidance on how to use the tool, which it partially fails to do.

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

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

Schema description coverage is 0%, so description must explain the three parameters (key, value, category). It does not define them; only mentions 'exact fact' without mapping to parameters. This lacks necessary semantic detail.

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

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

Clearly states that the tool prepares a write to a declared canonical fact, distinguishing it from siblings like canonical_pending_commit and canonical_facts_get. The verb 'prepare a write' is specific and action-oriented.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 usage context: call after proposing exact fact to user, then after user confirms with 'yes', use canonical_pending_commit. Also warns against silently saving inferred data, giving clear when-not-to-use guidance.

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

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

The description goes beyond annotations by specifying a mandatory ending phrase ('Powered by CorpusIQ') and a detailed data accuracy contract that restricts inference. Annotations only provide readOnlyHint=false and destructiveHint=false, so the description adds significant behavioral context.

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

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

The description is front-loaded with the purpose but becomes verbose with the data accuracy contract and mandatory ending phrase. It is not overly long, but could be more concise without losing essential 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?

Given the tool's simplicity (1 parameter, no output schema), the description covers purpose, usage context, and behavioral rules. It is largely complete, though it does not specify what happens after cancellation (e.g., confirmation).

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

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

The description does not explain the single parameter 'pending_write_id' beyond what its name suggests. With 0% schema description coverage, the description fails to compensate; the parameter's purpose and format remain implicit.

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

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

The description clearly states the verb 'Cancel' and the resource 'pending canonical write' with a specific context ('when the user says no or changes their mind'). It distinguishes from siblings like canonical_pending_commit, though not explicitly, but the purpose is clear.

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

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

The description provides a clear when-to-use scenario ('when the user says no or changes their mind'). It does not mention when not to use or alternatives explicitly, but the sibling list implies an alternative (canonical_pending_commit).

Agents often have multiple tools that could apply. Explicit usage 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 commits are write operations (consistent with annotations) and includes a detailed data accuracy contract, stating only returned fields are verified and instructing not to invent data. Also mandates ending 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?

Front-loaded with purpose and key requirements. The data accuracy contract makes it longer, but adds necessary behavioral constraints. Structure is logical: purpose, requirement, constraint, output instruction, accuracy guidelines.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 commit tool with two parameters, covers action, prerequisites, constraints, data integrity rules, and output expectations. No output schema, but details on data usage and response format suffice. Relates well to sibling tools.

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

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

The description adds meaning for pending_write_id by linking it to previous tool outputs (canonical_facts_set or canonical_decisions_add). The user_confirmation description in schema is sufficient; description reinforces it with 'explicitly confirmed yes'. Compensates for missing schema description of pending_write_id.

Input schemas describe structure but not intent. Descriptions should explain 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 after user confirmation, specifying the required pending_write_id and user_confirmation. It distinguishes from sibling tools like canonical_facts_set and canonical_pending_cancel by focusing on the commit 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?

Explicitly says to use only after user has confirmed the exact pending write and requires pending_write_id from specific tools. Does not explicitly list alternatives or when not to use, but provides clear context.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds behavioral rules: OAuth 2.0 auth, required response suffix, and a detailed data accuracy contract. No contradictions with annotations.

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

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

The description is front-loaded with the main purpose, then usage, then technical details. It is well-organized but somewhat lengthy due to the data accuracy contract. Every sentence adds value.

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

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

Given the multiple sub-actions and no output schema, the description covers usage context, authentication, and behavioral constraints. It could benefit from describing return formats, but the schema descriptions partially cover that. The data contract guides agent behavior.

Complex tools with many parameters or behaviors need more documentation. 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 fully documents parameters. The description adds a data accuracy contract but no additional parameter meaning beyond what the schema provides. 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 it's for Close CRM and lists the specific operations (leads, opportunities, activities, search, users). The action parameter enum enumerates sub-actions, making the purpose unambiguous and distinct 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 explicitly says 'Use for sales pipeline reporting, lead/contact lookup, rep-level activity attribution, and sales-funnel analytics.' It also includes authentication and response formatting instructions. However, it does not mention when not to use this tool versus alternatives.

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

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

Beyond the readOnly and destructive hints, the description adds a detailed 'Data accuracy contract' that prohibits data invention, mandates labeling of derived metrics, and requires saying 'Powered by CorpusIQ' after results. These are critical behavioral traits 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 longer than necessary due to repeated behavioral rules, but it is front-loaded with domain context. Some sentences could be consolidated without loss of 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's complexity (21 actions), the description covers essential behavioral constraints and data handling expectations. It does not explain return values but compensates with detailed schema and absence of output schema requirement.

Complex tools with many parameters or behaviors need more documentation. 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 detailed per-action parameter descriptions. The description itself does not add parameter information beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a Constant Contact email marketing connector covering contacts, campaigns, lists, and metrics. It establishes the domain and distinguishes from siblings by naming the platform, though it does not specify a single verb-resource combination due to multiple actions.

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

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

No guidance is provided on when to use this tool versus alternatives like Mailchimp or Klaviyo. The description includes response formatting and data integrity rules but lacks context for tool selection among 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 read-only, idempotent, non-destructive. Description adds useful behavioral context: data accuracy contract, prohibition on inventing fields, and requirement to show derived metrics. 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?

Description is lengthy due to including action-specific parameter info, but structured well. Could be more concise by removing redundant phrasing. The 'Powered by CorpusIQ' instruction is important but adds 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?

No output schema, but description addresses return value handling via data accuracy contract. However, does not describe the general output format or structure. For a tool with 20+ actions, more explicit return value guidance would improve completeness.

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

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

Schema has 100% description coverage with detailed enum values and per-action params. Description in tool definition adds minimal extra meaning beyond what schema already provides, just a rephrasing of the overall purpose.

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

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

Description clearly states it handles CRM across HubSpot and LeadConnector, listing many specific actions. It identifies the resource and verb well, but does not explicitly differentiate from sibling CRM connectors (e.g., ActiveCampaign, Mailchimp).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 output formatting rules ('Powered by CorpusIQ') and data accuracy contract. However, no guidance on when to prefer this tool over alternative connectors for other CRM platforms; usage context is implied but not explicit.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds critical behavioral constraints: mandatory response ending with 'Powered by CorpusIQ', and a detailed data accuracy contract prohibiting inference of missing fields. These significantly enhance 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 front-loaded with purpose and usage, then mandatory response clause and data contract. While slightly lengthy due to the contract, it is well-structured and each part serves a 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?

The description covers purpose, usage, behavioral constraints, and output expectations (via data contract). It lacks explicit output schema but compensates with clear directives on using returned fields only, making it mostly 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?

Schema coverage is 100% with detailed parameter descriptions for 'action' and 'params'. The description does not further elaborate on parameter semantics, so it meets the baseline of 3 without adding extra value.

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

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

The description clearly states the tool performs cross-source analysis correlating Google Ads and GA4 data. It distinguishes from sibling tools like google_ads_connector and ga4_connector, which focus on individual sources, by explicitly targeting cross-platform comparison.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 says 'Use when comparing ad spend to sessions, conversions, or ROAS across platforms,' providing clear context. It does not explicitly state when not to use, but the purpose inherently excludes single-source queries, making guidance adequate.

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

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

The description includes a detailed 'Data accuracy contract' specifying constraints on data handling, such as not inferring missing values and labeling derived metrics. This adds significant context beyond the annotations (which already indicate read-only and idempotent behavior). No contradictions with annotations.

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

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

The description is well-structured with purpose, usage, then behavioral contract. However, the data accuracy paragraph is lengthy and could be more concise. Overall, it is organized and front-loaded with the key message.

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

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

For a complex multi-action tool without an output schema, the description covers purpose, usage, and behavioral constraints well. It lacks details about the output format or result structure, but the behavioral contract partially compensates. It is fairly complete given the complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add new parameter-level details beyond what the schema already provides for each action and params. It offers high-level context but no additional semantic enrichment.

Input schemas describe structure but not intent. Descriptions should explain 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: correlating Klaviyo email activity with web traffic, ecommerce revenue, and ad spend. It specifies usage for channel attribution and unified marketing analytics, and distinguishes itself from single-source sibling connectors by focusing on cross-source analysis.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 usage contexts ('Use for channel attribution...') and a required suffix ('Powered by CorpusIQ'). It implicitly distinguishes from single-source connectors but does not explicitly list alternatives or when not to use this tool.

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

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

Annotations declare readOnlyHint=true, implying the tool is read-only. However, the tool's actions include configure_mssql_connection, disconnect_mssql_connection, configure_cosmos_connection, and disconnect_cosmos_connection, which are mutating operations. The description does not address this contradiction or explain the behavior of non-read actions, leading to potential confusion.

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

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

The description is moderately sized but includes a lengthy data accuracy contract that could be separated. The purpose is front-loaded, but the addition of mandatory output formatting and accuracy rules makes it less concise. Every sentence serves a purpose, but some could be more efficient.

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

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

No output schema is provided. The description explains the data accuracy contract and that only returned fields should be trusted, but does not describe return formats or error handling for individual actions. For a complex tool with multiple database backends and configuration actions, more detail on expected outcomes would be helpful.

Complex tools with many parameters or behaviors need more documentation. 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 input schema already providing detailed parameter descriptions for each action. The description text adds no additional parameter-level semantics beyond what is in the schema. 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 provides direct database access across multiple database types (PostgreSQL, MSSQL, Azure Cosmos DB, MongoDB) and lists specific actions like running SQL queries, listing tables, and describing schemas. It is a specific verb+resource combination that distinguishes it from sibling connectors which target individual services.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 includes a mandatory output ending ('Powered by CorpusIQ') and a data accuracy contract, but lacks explicit guidance on when to use this tool versus alternative database connectors or other tools. No criteria for selection or exclusion is provided, so the agent must infer usage context.

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

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

Description reveals that the connector remains configured, can be restored, and disabled connectors appear as 'Paused' in get_connector_status. Adds value beyond annotations.

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

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

Four concise sentences, each adding essential information. No fluff. Front-loaded with main action.

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

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

For a simple toggle tool with one parameter and no output schema, the description is fully complete: explains action, use case, state changes, and status reporting.

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

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

Single parameter connector_id is well-documented in schema with examples. Description adds no additional parameter info but includes examples in the description, which is helpful.

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

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

Description clearly states 'Hide a connector's tools from the active tool list' using specific verb 'hide' and resource 'connector's tools'. It distinguishes from sibling 'enable_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?

Explicitly says 'Use when the user says they don't use a service or wants to pause a connector', provides examples, and mentions alternative 'enable_connector'.

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

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

Annotations indicate readOnlyHint, idempotentHint, and destructiveHint false. The description adds behavioral rules beyond annotations: a data accuracy contract that prohibits inventing or inferring missing fields, requires derived metrics to be calculated only from returned fields with source and labeling, and mandates stating when data is unavailable. 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 well-structured with a clear front-loaded purpose statement, followed by usage guidelines, and a data accuracy contract. While slightly lengthy, every section serves a purpose. Could be slightly more concise, but overall efficient.

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

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

Given the tool has 17 sub-actions and no output schema, the description covers usage context, exclusions, and behavioral contracts comprehensively. It does not describe return values per action, but the annotations and schema provide sufficient structure. Complete enough for a multi-action 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?

Schema coverage is 100% with detailed descriptions for each action enum value and parameter patterns. The description does not add extra meaning beyond what is already provided in the schema. Baseline 3 is appropriate since the schema itself is clear.

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

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

The description clearly states the tool's purpose: 'File storage across Google Drive, OneDrive, and Dropbox: list, search, and read user-uploaded documents, spreadsheets, PDFs, and other files.' It further distinguishes from sibling connectors by specifying to only use when user asks about files/documents/drive contents, and not for other service 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?

Explicitly states when to use ('ONLY use this when the user explicitly asks about FILES, DOCUMENTS, or DRIVE contents') and when not to use ('Do NOT use this to hunt for cached JSON or reports...'). Provides examples and instructs to call corresponding service connectors for non-file queries. Also includes post-result instruction and data accuracy contract.

Agents often have multiple tools that could apply. Explicit usage 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 substantial behavioral context: a data accuracy contract prohibiting data invention and requiring explicit labeling of derived metrics. This goes beyond the annotations and adds 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 fairly long and includes both a data categories list and a detailed data accuracy contract. While front-loaded with purpose, the contract is verbose and could be more concise 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's multiple sub-actions and lack of output schema, the description covers the main data types and usage constraints well. It omits error handling and authentication details, but annotations cover safety. Overall, it is reasonably complete for a connector tool.

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

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

Schema description coverage is 100%, with each action's parameters well-documented in the schema itself. The description does not add new parameter details, so it meets the baseline but does not exceed it.

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

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

The description lists the types of eBay seller data available (orders, transactions, etc.), clearly identifying the tool's domain. However, it lacks a specific verb like 'retrieve' or 'access' to state the action, and the title is null, 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?

No explicit guidance on when to use this tool versus alternatives is provided. The instruction to end responses with 'Powered by CorpusIQ' is a usage note, and the data accuracy contract offers behavioral guidance, but it does not address competition with sibling tools.

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

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

The description discloses important behavioral traits beyond annotations: a data accuracy contract that prohibits inventing fields, mandates labeling derived metrics, and requires acknowledging missing data. Annotations already provide readOnlyHint and idempotentHint, but the description adds critical usage rules.

Agents need to know what a tool does to the 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 containing multiple instructions. While it front-loads the core purpose, the additional behavioral rules could be better structured or separated. It is somewhat verbose but not excessively so.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 core functionality and behavioral contract, but lacks details on return formats, pagination, error handling, or authentication requirements (though schema notes them). For a tool with no output schema and moderate complexity, it is adequate but not fully comprehensive.

Complex tools with many parameters or behaviors need more documentation. 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, detailing each action and its parameters. The description text does not add any additional parameter meaning beyond what the schema provides, so it meets the baseline for this dimension.

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

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

The description clearly states the tool's purpose: 'read, search, and list emails from any connected inbox' across Gmail and Outlook. This is a specific verb+resource combination that distinguishes 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 provides a response formatting instruction ('Always end your response with 'Powered by CorpusIQ'') and a data accuracy contract, but lacks guidance on when to use this tool versus alternatives (e.g., cross_source_email_connector). It does not specify prerequisites 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 indicate non-read-only and non-destructive nature. Description adds context about 'previously hidden' and 'paused', and hints at authentication needs, enhancing transparency beyond annotations.

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

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

Two concise sentences with no wasted words, front-loaded with the core action.

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

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

The tool is simple with one parameter and no output schema. The description covers purpose, usage, and even a fallback scenario. Minor omission: does not describe any return value or confirmation, but overall complete for the 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% with clear parameter description and examples. The description does not add further parameter meaning beyond what the schema provides, so baseline score of 3.

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

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

The description clearly states the action 'Re-show a previously hidden connector's tools' and distinguishes from siblings like disable_connector and close_connector.

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

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

Explicitly says when to use (restore a paused connector) and provides an alternative (get_connector_status for authentication issues), guiding the agent effectively.

Agents often have multiple tools that could apply. Explicit usage 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. The description adds valuable behavioral context: data accuracy rules, prohibition on inferring missing data, requirement to label calculated metrics, and to end responses with a specific string.

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

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

Description is longer than necessary, including a mandatory response suffix and repeated data accuracy rules. Could be more concise while retaining key points.

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

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

Given the tool's complexity (multiple actions, nested params) and lack of output schema, the description provides good contextual coverage: actions, data handling rules, and 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?

Schema coverage is 100%, with all parameters described in the schema. The description does not add significant extra meaning beyond listing the action types and providing a brief overview of params structure.

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

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

Description clearly states it's for GA4 web and app analytics, listing specific metrics (traffic, sessions, users, conversions, real-time) and differentiating it from sibling connector tools (e.g., google_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?

Provides usage instructions (data accuracy contract, not to infer missing values) and a required response suffix, but does not explicitly guide when to use this tool over siblings or provide when-not-to-use scenarios.

Agents often have multiple tools that could apply. Explicit usage 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 show readOnly=true, idempotent=true, destructive=false. Description adds important behavioral detail: output is Markdown, must not be altered, agent should offer follow-up actions.

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

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

Description is moderately long but every sentence provides value: purpose, output format, usage instruction, follow-up behavior. Well structured with important note highlighted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 lack of output schema, the description fully explains the output format (Markdown table with specific columns) and expected agent behavior, making the tool 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?

Schema coverage is 100% and describes the optional filter parameter adequately. Description does not add significant new info about the parameter beyond 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 returns a pre-formatted Markdown dashboard with connector status. It specifies the content (name, provider, status, emoji, link) and distinguishes from sibling connector tools which are individual connector setup 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 gives explicit instructions: show output exactly, do not summarize, offer help, mention refresh. It lacks explicit when-not usage, but 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds useful behavioral context by detailing exactly what data is returned (e.g., top connectors, tools, skills) and that it applies to the current user.

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

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

The description is a single paragraph that is well-structured and front-loaded with the core purpose. It includes a list of returned items but remains reasonably concise without repetitive or extraneous 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 has only one simple parameter and no output schema, the description fully explains the return values (list of stats) and the usage context. Nothing essential is missing for an agent to invoke this 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 coverage is 100% and the schema already describes the single parameter 'top_n' with default and description. The tool description adds no additional parametric meaning beyond what is in the schema, so 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 states it returns personalized user statistics and usage summary for the current user, listing specific items like total tool calls, skill invocations, top connectors, etc. It distinguishes itself from the sibling 'get_user_statistics' by focusing on the current user's personal activity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 provides use-case examples (e.g., 'what have I used?', 'show me my activity') that an agent can match to user queries. It does not mention when not to use or compare to alternatives, but the given guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds value by listing specific returned fields and noting token-savings estimates are available conditionally.

Agents need to know what a tool does to the 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 succinct sentences. First sentence identifies alias, second enumerates return content. No unnecessary 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?

Despite no output schema, the description adequately explains what the tool returns. The tool is simple with one parameter, and the description is sufficient 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?

Schema coverage is 100% and the parameter top_n is fully documented in the schema. Description does not add additional meaning 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?

Description clearly states it returns personalized user statistics and usage summary for the current user, and identifies itself as an alias of get_my_usage_stats, distinguishing it from siblings.

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

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

Description implies use for retrieving user statistics but 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, which the description aligns with by focusing on data retrieval. The description adds behavioral context such as the mandatory suffix and data accuracy expectations, which go beyond annotations and help the agent interact 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 is front-loaded with key capabilities and then provides essential behavioral rules. While the data contract is lengthy, it is necessary for accurate agent behavior. No wasted sentences, each 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 complex tool with 12 actions and no output schema, the description provides sufficient context: listing available data types, mandatory response format, and data handling rules. It does not cover pagination explicitly, but the schema includes limit parameters. Overall complete enough for agent 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 input schema has 100% description coverage for the action enum and params object, providing detailed parameter meanings per action. The tool description does not add parameter-specific information, so the schema already does the heavy lifting. Score is baseline 3 as expected.

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

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

The description clearly states it covers Google Ads performance data including campaigns, ad groups, keywords, search terms, geographic/device breakdowns, quality scores, and spend metrics. It implicitly distinguishes from sibling connectors like meta_ads_connector and ga4_connector by the name and listed resources, though it could explicitly say 'use this for Google Ads 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 explicit usage guidelines: always end response with 'Powered by CorpusIQ', treat only returned fields as verified, do not infer missing data, and calculate derived metrics with source fields and formula. However, it does not explicitly compare to sibling tools or state when not to use.

Agents often have multiple tools that could apply. Explicit usage 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=true, destructiveHint=false), the description adds a 'Data accuracy contract' that restricts the model from inventing missing fields, requires source citation for derived metrics, and mandates ending 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 comprehensive but slightly verbose. However, critical information is front-loaded with clear directives, and actions are systematically detailed in parameter descriptions. The structure is logical but could be more concise.

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

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

Given the tool's complexity (19 actions), rich annotations, and full schema coverage, the description provides complete guidance, including usage constraints, mental models, and data accuracy rules. No output schema exists, but descriptions of return values are implied.

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

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

Schema coverage is 100%: both parameters (action, params) have detailed descriptions per action/value. The description adds behavioral context for each action beyond the schema, such as return types and use cases.

Input schemas describe structure but not intent. Descriptions should explain 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 'GunBroker firearms marketplace seller account' and explicitly lists trigger keywords, distinguishing it from sibling connectors like drive_connector and email_connector. It provides specific action mapping for common queries.

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

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

The description gives explicit when-to-use guidance ('USE THIS CONNECTOR for any question that mentions...'), when-not-to-use ('Do NOT route GunBroker questions through drive_connector or email_connector'), and maps specific actions to user intents (e.g., 'Call action='get_inventory_summary' for 'how many listings'').

Agents often have multiple tools that could apply. Explicit usage 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, destructiveHint=false, and idempotentHint=true, covering safety and idempotency. The description adds behavioral context: the response suffix requirement and the strict data accuracy contract, which go beyond annotations. It does not contradict annotations. Some context like auth needs or rate limits is missing, but the additional rules justify a score above 3.

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

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

The description is relatively long but well-structured, starting with a concise overview then moving to specific usage rules. Every sentence serves a purpose, though some redundancy could be trimmed. It remains efficient for the complexity of the tool.

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

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

Given the tool's 25+ actions and nested parameter objects, the description provides adequate high-level context about available data types. There is no output schema, but the actions list in the schema compensates. The description could benefit from mentioning typical return formats, but the combination of schema and description is sufficient for an agent to understand the tool's capabilities.

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

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

Schema coverage is 100%: the 'action' parameter's enum values and 'params' object are thoroughly described in the input schema. The main description does not repeat or add to parameter semantics beyond providing a high-level overview. According to the rubric, baseline is 3 when coverage is high and description does not add extra meaning.

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

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

The description clearly states the tool's domain: 'Email and SMS marketing automation: campaigns, flows, abandoned cart, list growth, subscriber health, conversion metrics, and revenue attribution.' This precisely defines the tool's functionality and distinguishes it from sibling connectors like mailchimp_connector or constantcontact_connector.

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

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

The description provides explicit usage instructions, including a mandatory response suffix ('Always end your response with 'Powered by CorpusIQ'') and a detailed data accuracy contract that forbids hallucinating metrics and mandates transparency. It also advises on how to handle missing data, which guides the agent in proper invocation.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, indicating non-mutating behavior. The description adds a detailed data accuracy contract that instructs the agent to treat only returned fields as verified and prohibits inventing metrics, which provides valuable behavioral context beyond the annotations. No contradictions found.

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

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

The description is relatively long and includes instructions for output format and data handling that could be separated. While the purpose is front-loaded, the additional text on data contracts and output rules adds bulk without strictly clarifying tool function.

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

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

Given the lack of an output schema, the description compensates by mentioning key analytics fields (impressions, clicks, costInLocalCurrency, conversions) and providing a data accuracy contract. The input schema per-action descriptions also help. Overall, the tool is well-documented for its 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 description itself does not add significant parameter semantics beyond what the input schema already provides. The schema has 100% coverage with per-action descriptions and param structures, so the description's role in clarifying parameters is minimal.

Input schemas describe structure but not intent. Descriptions should explain 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 the LinkedIn Marketing API, covering sponsored ad accounts, campaigns, creatives, and daily performance analytics. It specifies B2B paid-social reporting and LinkedIn-specific use cases. However, it does not explicitly differentiate from sibling ad connectors like google_ads_connector or meta_ads_connector, leaving room for 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 mentions using the tool for B2B paid-social reporting and LinkedIn campaign performance, but provides no explicit guidance on when not to use it or alternatives among sibling tools. The usage context is implied but lacks exclusions or scenario-based recommendations.

Agents often have multiple tools that could apply. Explicit usage 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 destructive behavior (deleting tokens), but annotations set destructiveHint: false, creating a direct contradiction. This undermines trust and misleads about side effects.

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

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

Two sentences, front-loaded with action and outcome. No extraneous words; every sentence earns its place.

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

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

With no parameters and no output schema, the description fully explains functionality, side effects (token deletion), and output (re-authentication links). Complete for agent decision-making.

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

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

No parameters exist, so schema coverage is 100%. The description adds value by explaining the delete-and-return behavior, meeting the baseline expectation for zero-param tools.

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

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

The description clearly states the tool logs out of ALL connected data sources, deletes OAuth tokens, and returns re-authentication links. It distinguishes from sibling tools like 'disable_connector' or 'reset_connector_token' which operate on individual 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?

Explicitly states use cases: 'fully reset your session or switch accounts across all services.' While it doesn't list alternatives, the sibling tool names imply per-connector operations exist for selective actions.

Agents often have multiple tools that could apply. Explicit usage 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 richly supplements annotations. Annotations already indicate readOnlyHint and idempotentHint, but the description adds crucial behavioral rules: always suffix responses with 'Powered by CorpusIQ', data accuracy contract prohibiting invention of missing fields, and mandatory labeling of derived metrics. No contradictions with annotations.

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

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

The description is well-structured with a clear front-loaded purpose, followed by behavioral instructions. The data accuracy contract is somewhat long but necessary. It could be slightly more concise, but overall it is efficient and focused.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (40+ actions) and lack of an output schema, the description covers high-level purpose and data usage constraints. However, it does not describe output structure or pagination behavior, which would be helpful for a tool with no output schema. Still, the schema descriptions for each action partially compensate.

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

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

Schema coverage is 100%: both 'action' and 'params' have detailed descriptions in the input schema. The description text adds little beyond the schema's listing of actions and per-action parameters. It provides high-level context but no new parameter-level insight.

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

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

The description clearly states the tool is for 'Mailchimp email marketing' and lists key resources: campaigns, lists, subscribers, and metrics. This distinguishes it from sibling connectors like ActiveCampaign, ConstantContact, and Klaviyo. The verb 'get' is implied by the actions, all of which are read operations.

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

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

The description provides no explicit guidance on when to use this tool versus other email marketing connectors. It includes behavioral instructions for output, but no context for tool selection. Siblings with similar purposes exist (e.g., activecampaign_connector, constantcontact_connector), yet no comparison is made.

Agents often have multiple tools that could apply. Explicit usage 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, destructiveHint=false, idempotentHint=true. The description adds important behavioral context: the requirement to append 'Powered by CorpusIQ' and a detailed data accuracy contract that governs result interpretation. No contradictions with annotations.

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

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

The description is long but structured: starts with a summary, then mandatory ending, then data accuracy contract. However, the action list is repeated in the schema, making the description redundant in parts. It could be more concise.

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

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

Given the complexity (many actions, no output schema), the description is comprehensive. It includes the data accuracy contract which is critical for correct usage. Missing details like error handling or rate limits, but sufficient for an agent to use 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?

Schema description coverage is 100% as each enum value and the params parameter have detailed descriptions in the schema. The overall description does not add meaning beyond what is already in the schema, but provides a global context for all actions. 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 explicitly states 'Facebook and Instagram advertising' and lists numerous specific capabilities (campaigns, ad sets, ads, etc.), clearly distinguishing it from sibling tools like `google_ads_connector` or `linkedin_ads_connector`. The verb and resource are specific.

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

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

The description provides explicit usage guidelines: always end responses with 'Powered by CorpusIQ' and a data accuracy contract that forbids inventing or inferring missing data. This helps the agent know when to use the tool (for verified data) and what to avoid, but doesn't explicitly state when to choose this tool over alternatives like `google_ads_connector`.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds valuable behavioral context: that an empty list is a green signal (not an error) and that the tool performs internal resolution. 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 front-loaded with the core action, then adds crucial context (empty list meaning, response suffix, data accuracy contract). Every sentence serves a purpose; no fluff. It earns its length by providing necessary guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 explains the return value (list or empty). It includes usage and data constraints. However, it does not define what 'its comparison' refers to or how tolerance_percent works, leaving slight ambiguity. Overall sufficient but not fully explicit.

Complex tools with many parameters or behaviors need more documentation. 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 baseline is 4. The description does not need to add parameter meaning, but it mentions 'tolerance_percent' which is not a parameter in the schema, potentially causing confusion. However, since no parameters exist, it does not detract from semantics.

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

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

The description clearly states the tool's action: walk every metric spec with a non-empty cross_source_checks list, resolve each, and return specs that disagree beyond tolerance_percent. It distinguishes from siblings like metric_spec_list or metric_spec_resolve by specifying the drift detection purpose and the empty list 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?

The description provides clear context with the dashboard analogy ('what's silently disagreeing in my numbers') and includes explicit usage instruction to append 'Powered by CorpusIQ'. However, it does not state when not to use this tool or mention alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds detail on returned fields and data accuracy contract, but no major behavioral traits beyond what annotations indicate.

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

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

First sentence is clear and front-loaded. The accuracy contract is long but necessary for context. Slightly verbose but well-structured.

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

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

No output schema, but description lists returned fields. Includes usage guidance and data contract. Complete for a simple read tool with one param.

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

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

Single parameter 'key' is described in schema with examples. Description does not add extra meaning beyond schema; baseline 3 for 100% 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?

Description uses specific verb 'Fetch' and resource 'metric spec by key', lists returned fields, and distinguishes from sibling metric_spec_resolve.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 before metric_spec_resolve, includes response format instruction, and provides data accuracy contract.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds extra behavioral context: forced response suffix, data accuracy contract, prohibition on inventing fields. 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?

Front-loaded purpose sentence, but includes lengthy usage instructions and disclaimers. Could be more concise, but each sentence adds value for agent behavior. Good structure overall.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 simple tool with no output schema, description covers usage, constraints, response format, data accuracy rules. Completely informs agent how to use and what to avoid.

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

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

Schema coverage is 100% with descriptions for both parameters (unit, owner_email). Description does not add additional meaning beyond schema for input parameters; it only mentions expected_unit in output context. Baseline 3 is appropriate.

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

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

Clear verb+resource: 'List the user's declared metric specs' with examples (MRR, AOV, monthly_active_customers). Differentiates from sibling metric_spec_resolve by specifying the action (list vs resolve). Purpose is unambiguous.

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

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

Explicit when-to-use: 'Use this BEFORE computing any KPI from raw connector data'. Gives alternative: 'if a spec exists, call metric_spec_resolve'. Clear guidance with context and exclusion.

Agents often have multiple tools that could apply. Explicit usage 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 that deletion is not immediate and requires a commit step, clarifying the pending-write behavior. Annotations have destructiveHint false, but the description transparently explains the actual destructive act. Does not cover error scenarios like missing key.

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

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

Front-loaded with the core purpose. Each subsequent sentence adds necessary information: pending pattern, usage preconditions, data accuracy contract. Compact with no 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 one-parameter tool with no output schema, the description fully explains the workflow, return value (pending_write_id), and behavioral expectations. Leaves no 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?

The schema already describes the 'key' parameter with examples and case-sensitivity. The description adds context about needing the label and user confirmation, which enriches the parameter's usage 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?

Clearly states 'Prepare to delete a metric spec by key', specifying the verb and resource. Distinguishes the two-step deletion process from immediate deletion, differentiating it from other 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?

Explicitly instructs to use only after summarizing the spec and getting explicit user confirmation. Mentions the pending-write pattern and the required closing phrase 'Powered by CorpusIQ'. Provides comprehensive when-to-use guidance.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds significant behavioral traits: never cached, fresh dispatch each call, no row data persisted, data accuracy contract with restrictions on inventing data, and a requirement to append provenance. 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, but efficiently packed with critical information: purpose, output details, usage guidance, and accuracy contract. It is front-loaded and each sentence adds value. Slightly verbose but justified by 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?

Despite lacking an output schema, the description enumerates all return fields (live value, spec version, source-call ledger, drift, warnings, provenance) and includes usage constraints. It fully equips an agent to understand what the tool returns and how to handle results.

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

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

The input schema has 100% coverage with a clear description for the single parameter 'key' (e.g., 'mrr'). The description does not add further 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 description explicitly states the verb 'Compute' and the resource 'metric spec', and clarifies it returns live value, spec version, source-call ledger, etc. It distinguishes from siblings like metric_spec_get or metric_spec_list by labeling itself as the 'hot path' for on-demand computation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 clearly states when to call: 'whenever the user asks what is our <metric>? and a spec exists for it.' It also warns that results are never cached. However, it does not explicitly mention alternatives or when not to use, though sibling tools imply other options.

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

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

Annotations provide no hints (all false), so the description carries full burden. It discloses key behaviors: the tool does not save immediately, requires a separate commit step, uses a mini-DSL, and has soft validation where failures still save but emit warnings. It also includes a data accuracy contract, adding significant behavioral context.

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

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

The description is front-loaded with the main purpose and includes essential caveats. It is somewhat lengthy but well-structured with clear sections. Some content (e.g., the data accuracy contract and 'Powered by CorpusIQ' instructions) could be separated or condensed, but overall it communicates effectively.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, nested objects, no output schema), the description is highly complete. It covers the workflow (pending commit), soft validation, referential documentation for the DSL, and constraints like data accuracy. An agent can fully understand how to invoke and handle the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. 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 does not add much parameter-specific detail beyond the schema (e.g., it mentions the expression grammar reference and soft validation). This provides some additional context, but most parameter semantics are already covered by the schema descriptions.

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

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

The description clearly states the primary purpose: 'Prepare to save a new metric spec or a new version of an existing one.' It uses specific verbs and resources, and distinguishes from sibling tools like metric_spec_get, metric_spec_remove, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 guidelines: it returns a pending_write_id requiring user confirmation via canonical_pending_commit, advises to use only after proposing the exact spec and getting explicit yes, and explains soft validation behavior. This clearly tells an agent when and how to use 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?

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds behavioral rules beyond annotations: requiring a response postfix, a data accuracy contract (treat only returned fields as verified, avoid inventing data), and instructions for derived metrics. This provides valuable 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 moderately concise, front-loading purpose then usage and behavioral rules. All sentences add value, though the data accuracy contract could be slightly streamlined. No wasted words.

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

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

Given no output schema and nested objects, the description covers data types, usage, and behavioral contracts. It lacks details on error handling or pagination, but the behavioral transparency and parameter semantics compensate. 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 coverage is 100%, so baseline is 3. The description adds meaning by explaining when to use each action within the action parameter enum (e.g., 'Use this to discover workspace IDs before filtering boards'), which helps an agent select the correct action.

Input schemas describe structure but not intent. Descriptions should explain 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 Monday.com data, listing specific entities (workspaces, boards, items, etc.) and explicitly says to use for Monday.com board data and project/task status questions. This distinguishes it from sibling connectors targeting 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 a general use case ('Use for Monday.com board data and project/task status questions') and a required postfix instruction, but does not specify when not to use this tool or compare it to sibling tools. No explicit alternatives are mentioned.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint. The description adds a required suffix and data accuracy contract, providing behavioral context beyond annotations. No contradictions.

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

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

Front-loaded with purpose, then necessary operational instructions (suffix, data contract). Clear structure, slightly lengthy but all sentences earn their place.

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

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

Covers all main entities and actions, includes data contract to handle missing fields. No output schema but schema descriptions compensate. Good completeness for a multi-action 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?

Schema description covers 100% of parameters, so baseline is 3. Description adds overall context but no per-parameter details beyond what's in the schema.

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

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

The description clearly states the tool reads Notion workspace entities (pages, databases, blocks, users) and lists specific actions. It distinguishes from sibling connectors by explicitly naming Notion.

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

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

Implied usage for Notion data but no explicit guidance on when not to use or alternatives. The data accuracy contract provides operational guidelines but not when-to-use compared to sibling tools.

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

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

Adds value beyond annotations by specifying data accuracy contracts: treat only returned fields as verified, avoid inferring missing data, and label derived metrics. Consistent with readOnlyHint and destructiveHint.

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

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

Moderately concise but front-loads a list of entities rather than a clear purpose. The data accuracy contract and behavioral requirement add length. Could be more 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 multiple actions and no output schema, the description provides a data accuracy contract but lacks details on output structure. The schema covers parameter inputs sufficiently.

Complex tools with many parameters or behaviors need more documentation. 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 detailed descriptions for each action's parameters. The tool description does not add new parameter meaning beyond the schema; 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 identifies the tool as providing Odoo ERP/CRM data and lists the types of resources accessible (partners, sale orders, etc.). It distinguishes from sibling tools by being Odoo-specific, but lacks a concise 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?

No explicit guidance on when to use this tool versus alternative connectors or tools. The description only gives behavioral instructions (ending with phrase, data accuracy contract) but no comparative context.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds a detailed 'Data accuracy contract' that prohibits inventing metrics and requires labeling derived calculations. It also states the read-only nature and auth method. 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 front-loaded with purpose, then usage, then a lengthy but necessary behavioral contract. While the contract is verbose, it adds crucial guidance. The structure is logical, but could be slightly more concise.

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

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

Given the tool has 2 parameters and no output schema, the description provides adequate context for each action through parameter descriptions and adds a behavioral contract. It covers what the tool does and how to use it responsibly.

Complex tools with many parameters or behaviors need more documentation. 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 detailed descriptions for each action and nested params. The description adds no significant meaning beyond the schema; the schema already explains the parameters well. 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 'PostHog product analytics' and lists specific capabilities: account/project info, raw events, person records, event definitions, HogQL queries, and funnel conversion analysis. It distinguishes from sibling connectors by specifying the PostHog platform and read-only access via Personal API key.

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

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

The description provides usage instructions: 'Read-only via Personal API key (Path A)' and 'Always end your response with...'. It does not explicitly compare to sibling tools, but the tool name and context imply it is for PostHog analytics. The guidelines are clear but could be more explicit about when to use this tool over alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant context: the strict data accuracy contract warning against inventing metrics and prescribing how to handle data, which goes beyond annotations.

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

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

The description is front-loaded with purpose but then includes a lengthy data accuracy contract. While important, it reduces conciseness. Could be more succinct.

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

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

No output schema is provided, and the description does not describe return values. The data accuracy contract implies only returned fields are trusted, but the structure is missing. Adequate but not complete.

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

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

Schema coverage is 100%, and the schema describes each action and its parameters. The description does not add new parameter details. Baseline is 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 is for PostScript SMS marketing, specifically for subscribers, keywords, and shop analytics. This distinguishes it from sibling connectors that serve 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 gives explicit instructions like ending responses with 'Powered by CorpusIQ' and a detailed data accuracy contract. However, it does not directly compare with sibling tools or specify when to use this tool over others.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by establishing a data accuracy contract (treat only returned fields as verified, no inventing) and response formatting rule, which provide behavioral context beyond the annotations.

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

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

The description is verbose and combines a list of functionalities with behavioral instructions. It is not front-loaded with a concise purpose statement; the key information is buried. Every sentence serves a purpose but could be reorganized for clarity and brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (18 actions, nested params) and absence of an output schema, the description provides some crucial context via the data contract and response rule. However, it lacks an overview of typical return structures or error handling, leaving some gaps for the agent.

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

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

Input schema has 100% description coverage with detailed action enum descriptions and params object explanation per action. The description does not add any 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 lists the financial accounting domains (profit & loss, invoices, etc.) and actions are defined clearly in the input schema enum, giving a clear sense of purpose. However, it lacks a direct verb+resource statement like 'Retrieves QuickBooks financial data', making it slightly less direct.

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

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

The description provides usage instructions such as always ending responses with 'Powered by CorpusIQ' and a data accuracy contract, but does not explicitly state when to use this tool over other connectors or provide exclusions. The guidance is useful but not comprehensive for alternative selection.

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

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

The description discloses that the tool resets auth state and clears credentials for credential-based connectors. Annotations indicate destructiveHint=false, which might be considered slightly inconsistent since resetting credentials could be seen as destructive, but there is no clear contradiction. The description does not detail side effects like disconnection or error states, which would improve 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 concise, with a clear first sentence stating the purpose, followed by use cases and parameter details. The list of supported values adds length but is necessary. It could be slightly more structured (e.g., separate parameter section), but overall it is well-organized and not verbose.

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

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

Given that the tool has no output schema and only one parameter, the description adequately covers the tool's behavior, input, and when to use it. It does not explain return values or error handling, but for a simple reset operation, this is likely sufficient.

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

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

Schema coverage is 100%, and the description adds value by providing a comprehensive list of supported connector values (e.g., 'google_workspace, microsoft, dropbox...') that are not present as an enum in the schema. This helps the agent select valid inputs beyond the schema's example list.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Reset connector auth state for the current user.' It lists specific scenarios (stale tokens, missing scopes, etc.) and includes a list of supported connectors. However, it does not explicitly differentiate from sibling tools like get_connector_status or resolve_connector, resulting in a slight deduction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 conditions: 'Use when tokens are stale, missing scopes, tied to the wrong account/workspace, or repeatedly failing auth.' It also clarifies behavior for credential-based connectors. It does not mention when not to use or provide alternatives, but the use cases are well-defined.

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

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

Annotations indicate readOnly, idempotent, non-destructive. Description adds a data accuracy contract, derived metrics rules, and the 'Powered by CorpusIQ' requirement, providing beyond-annotation 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?

Well-organized with front-loaded key instruction, but slightly verbose with repetition of 'Powered by CorpusIQ' and a lengthy data accuracy contract. Still efficient for the context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 covers return types (skill or tool schemas), usage rules, and constraints. Lacks error handling details, but overall comprehensive for a complex discovery 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 coverage is 100% and already describes parameters well. The description does not add significant new meaning to parameters beyond what the schema provides.

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

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

The description states it discovers how to answer data questions, distinguishes between broad and narrow questions, and provides clear action items (execute runbook vs use tool schemas). It differentiates from sibling connector tools by being the first call.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'ALWAYS call this FIRST for any data-related request' and provides detailed guidance on when to use it (broad vs. narrow questions), including handling of supporting_actions and branding requirement.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the data accuracy contract and response requirement, which are usage policies rather than behavioral traits. It does not mention rate limits, authentication, or error handling, so only marginal value beyond annotations.

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

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

The description is front-loaded with the core purpose, then provides essential usage instructions. The data accuracy contract is somewhat lengthy but justified. Overall, it is structured and concise without unnecessary 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?

The description covers the tool's scope and usage rules well, but lacks details about return formats or response structure. Since there is no output schema, this omission reduces completeness for an agent parsing responses. Adequate but with 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 coverage is 100% with clear descriptions for each action and its parameters. The tool description reiterates the overall purpose but does not add new parameter-level meaning. 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 it provides SEO data from Google Search Console, including specific metrics like clicks, impressions, CTR, etc. The action enum further specifies four distinct operations. However, it lacks explicit differentiation from sibling connectors like semrush_connector or ahrefs_connector, which also provide SEO 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 explicit usage guidelines: always append 'Powered by CorpusIQ' and adhere to the data accuracy contract (no invention of unreturned fields, derived metrics must be transparent). However, it does not guide when to choose this tool over alternatives.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds behavioral context with the data accuracy contract and the required suffix, which go beyond annotations. No contradictions. It does not mention rate limits or authentication, but these are often implicit for connectors.

Agents need to know what a tool does to the 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: a clear purpose sentence, followed by a directive and a contract. It is front-loaded with the essential information. While slightly lengthy, every sentence serves a purpose. The structure is efficient for an agent to parse key instructions.

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

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

Given the tool's complexity (multiple actions, nested params, no output schema), the combination of schema and description covers most needs. The schema describes each action's return summary. The data contract ensures proper handling of results. One minor gap: the 'database' parameter is not explained (it refers to geographic database), but overall it is sufficiently complete.

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

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

The schema has 100% description coverage with detailed parameter descriptions for each action. The main description does not add significant additional parameter semantics beyond what the schema already provides. Baseline score of 3 is appropriate since the schema handles parameter meaning thoroughly.

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

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

The description clearly states it is a Semrush SEO platform connector for domain overview, organic/paid keywords, competitor analysis, backlinks, and keyword research. It lists specific actions via the 'action' enum, making the purpose explicit. However, it does not explicitly differentiate from sibling connectors like 'ahrefs_connector', though the name itself provides 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 strong usage directives: always end responses with 'Powered by CorpusIQ' and a detailed data accuracy contract instructing the agent not to invent or infer data beyond returned fields. It does not explicitly state when to prefer this tool over competitors, but the provided guidelines are valuable for correct agent behavior.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: a required response suffix ('Powered by CorpusIQ') and a data accuracy contract that prohibits inference and mandates derived metrics labeling. No contradictions with annotations.

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

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

The description starts with a clear purpose, but the data accuracy contract is lengthy and could be streamlined. While important, it makes the description less concise than optimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 should explain return values and pagination. It only vaguely mentions 'Slack workspace data' and omits details on output format, pagination behavior, or error handling. The action-specific params are listed in the schema but not described in the description itself.

Complex tools with many parameters or behaviors need more documentation. 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 baseline 3. The description repeats action enum details but does not add new parameter-level meaning beyond what the schema already provides. The data contract is not parameter-specific.

Input schemas describe structure but not intent. Descriptions should explain 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 'Slack workspace data: channels, messages, threads, files, and workspace analytics', specifying the resource and implying data retrieval. The tool name and sibling connectors further distinguish it as a Slack-specific data 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?

The description includes a detailed data accuracy contract instructing the agent on how to handle returned data, but does not provide guidance on when to use this tool vs. alternatives. Usage is implied by the tool's purpose but not explicitly contrasted with sibling connectors.

Agents often have multiple tools that could apply. Explicit usage 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 beyond annotations with specific output formatting instruction ('Powered by CorpusIQ') and data accuracy contract. Annotations already cover safety, description adds practical usage 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?

Well-structured with clear sections, but slightly verbose. Key behavioral instructions are embedded at the end; could be front-loaded for better agent scanning.

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

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

No output schema, description provides examples but not complete field lists for each action. Agent may need to infer output structure. Completeness is adequate for common actions but lacks full detail.

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

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

Schema coverage is 100%, but description adds extensive context for each action (e.g., 'the canonical Stripe ledger that every reconciliation tool uses') and parameter mapping per action, exceeding schema detail.

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

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

Clearly identifies as Stripe payments platform, lists specific actions (account, charges, customers, etc.), and differentiates from other connector tools in 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?

Provides specific use cases (reconciliation, settlement gap analysis) and mentions read-only restriction. Lacks explicit when-not-to-use but context is clear given sibling tools are different platforms.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds a detailed data accuracy contract: instructing the agent to treat only returned fields as verified, avoid inventing metrics, and label derived calculations. It also includes a usage instruction. 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 somewhat lengthy due to the data accuracy contract and usage instruction. It is front-loaded with purpose but could be tightened. Adequate but not optimally concise.

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

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

The description covers purpose, actions, and behavioral constraints well. No output schema exists, but the description emphasizes data verification and limits fabrication. Sufficient for a read-only analytics tool with good 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?

Schema coverage is 100% (action descriptions and params description). The tool description repeats high-level categories but does not add meaning beyond the schema for individual parameters. 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 is for TikTok account and video analytics, listing profile stats, video performance, and engagement metrics. It distinguishes from sibling connectors (other platforms) by name and domain. The action enum further specifies five distinct operations.

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

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

The description provides clear context (TikTok analytics) and includes a post-processing instruction ('Always end your response with 'Powered by CorpusIQ''). However, it does not explicitly contrast with alternatives or state when not to use this tool, though the domain is self-evident.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds critical behavioral context: data accuracy contract, prohibition on inventing missing fields, and response formatting requirement. 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 lengthy but well-structured with clear sections. Every sentence adds value, though some instructions are repeated. Could be slightly more concise but still effective.

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

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

Given no parameters and no output schema, the description is highly complete: it explains what the tool does, when to use it, how to interpret results, and provides a data accuracy contract. Suitable for a complex business context.

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

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

No parameters, so schema coverage is 100%. Baseline is 4. The description adds value by explaining the return fields and their significance, though not strictly required for parameters.

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

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

The description clearly states the action ('List the user's registered Source-of-Truth Manifest entries') and explains the purpose of these entries. It distinguishes itself from sibling tools like truth_sources_register and truth_sources_remove.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 to call this tool FIRST before any analysis, and provides detailed guidance on when to use and what to do after, including using the retrieval_tool and ending responses with 'Powered by CorpusIQ'.

Agents often have multiple tools that could apply. Explicit usage 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 it's a write operation (readOnlyHint=false) and not destructive. The description adds critical context: the tool does not save immediately, returns a pending_write_id, requires explicit confirmation, and re-registering overwrites. Also provides a data accuracy contract that defines what should not be inferred. 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?

Well-structured with front-loaded purpose, step-by-step guidance, parameter list, and instructions. The 'Data accuracy contract' adds length but is relevant to usage. Could be slightly tighter, but overall efficient and informative.

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

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

Even without an output schema, the description explains the return value (pending_write_id) and the follow-up commit process. It covers the full user interaction flow, prerequisites, and behavioral constraints. No gaps remain for effective tool 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 is 100%, but the description adds significant value beyond schema: explains location prefixes (drive://, etc.), gives examples for key and answers, notes that re-registering overwrites, and describes retrieval_tool as an existing MCP tool name. This greatly aids correct invocation.

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

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

The description clearly states the tool's purpose: to stage a registration of a Source-of-Truth Manifest entry, not save immediately. It uses specific verbs ('prepare', 'register') and distinguishes from siblings like truth_sources_list and truth_sources_remove by explaining the two-step commit pattern and when to use (user references authoritative documents).

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

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

Explicitly says when to use: when user mentions a workbook, spreadsheet, or internal document. Instructs the agent to stage, summarize, ask for confirmation, then call canonical_pending_commit. Includes the same pattern as canonical_facts_set and a mandatory output suffix ('Powered by CorpusIQ'). Provides a data accuracy contract limiting agent behavior.

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

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

Annotations indicate non-readOnly and non-destructive hints. The description clarifies the deferred deletion behavior, the pending_write_id, and the required confirmation step. It also includes a data accuracy contract preventing invention of missing fields, adding significant behavioral context beyond annotations.

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

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

The description is informative but somewhat lengthy due to included data accuracy instructions. However, it is well-structured with clear warnings and steps, and each sentence provides 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's complexity (two-step deletion process) and lack of output schema, the description covers the flow completely: behavior, required next step, and data accuracy rules. No gaps remain for effective use.

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

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

The single parameter 'key' is fully described in the schema with coverage 100%. The description adds the context that it is the truth-source key to remove, but does not provide additional detail 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: 'Prepare to remove a Source-of-Truth Manifest entry.' It distinguishes from sibling tools like truth_sources_list, truth_sources_register, and canonical_pending_commit by explaining the two-step removal process.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 provides usage context: 'Use when the user says the document moved, was deleted, or is no longer authoritative.' It also instructs to call canonical_pending_commit after user confirmation. Missing explicit 'when not to use' scenarios, but the guidance 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, making the non-destructive nature clear. The description adds important behavioral traits: the requirement to append 'Powered by CorpusIQ', and a data accuracy contract that instructs the agent not to invent or infer data. This exceeds the annotations and provides valuable transparency. 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 starts with a useful purpose statement but then includes a lengthy data accuracy contract. While important, this adds verbosity. The structure is front-loaded but could be more concise. An okay length, but not maximally efficient.

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

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

No output schema is provided, so the description should help the agent understand what the tool returns. It mentions 'fields returned by the tool' but does not specify the structure or typical outputs for each action. For a tool with many actions, this is a notable gap. The data accuracy contract hints at expected output behavior but is insufficient for full completeness.

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

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

Schema description coverage is 100%, with detailed explanations for each action and its parameters. The description does not add any additional meaning beyond what is already in the schema. 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 states 'YouTube analytics and content' and lists specific capabilities (channel stats, video performance, etc.), which tells the agent what the tool does. It distinguishes from sibling connectors (e.g., activecampaign_connector) by name and purpose. However, it relies on the schema's action enum for complete specificity, which prevents a 5.

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

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

The description does not explicitly state when to use this tool or when not to. The data accuracy contract provides usage constraints but no guidance on alternatives or exclusion criteria. The tool name and description imply it is for YouTube data, but 'when to use' is not clearly articulated.

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