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

The description adds behavioral context beyond annotations: 'Sends a cancellation request... job transitions to cancelled status. Already-committed data retained; only in-flight data discarded.' Annotations (destructiveHint=true, idempotentHint=true) are consistent.

Agents need to know what a tool does to the 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 front-loaded sections (behavior, when to use, returns, example). Every sentence adds value, no fluff.

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

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

For a simple cancellation tool, the description covers purpose, behavior, usage, return value, and example. Output schema exists, so further return details are not needed.

Complex tools with many parameters or behaviors need more documentation. 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 two parameters (job_id with description, response_format with enum), but context signals 0% schema description coverage. The tool description only provides an example with job_id, adding minimal 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 explicitly states 'Cancel a running sync or reset job', using a clear verb and resource. It distinguishes itself from siblings (no other cancel tool) and aligns with the annotation title 'Cancel Airbyte Job'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'When to Use' section lists two specific use cases (stop long-running/stuck sync, cancel accidental reset). It does not explicitly state when not to use or mention alternatives, but the context is sufficient for an agent.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, but description adds context that creation wires up a pipeline and returns connection details. Does not mention potential side effects like immediate sync start, but covers creation behavior adequately.

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

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

Well-structured with sections, bullet points, and examples. Front-loads the core purpose, then provides workflow and two examples. 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 input schema richness and presence of output schema, the description covers workflow, examples, and return info. No 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?

Input schema has extensive descriptions for all parameters (100% coverage), so description only adds examples and context about building the streams array. The description's workflow helps understand parameter use 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 'Create a new connection' and explains it links a source to a destination. It distinguishes from sibling tools like airbyte_create_source and airbyte_create_destination by specifying it's a pipeline between existing 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?

Has explicit 'When to Use' section and a 'Recommended Workflow' that specifies prerequisites (ensuring source/destination exist, calling airbyte_get_stream_properties). Examples illustrate usage.

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

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

Annotations are basic (readOnlyHint=false, etc.). Description adds context like requiring configuration schema and the creation workflow. Does not contradict annotations. Could mention idempotency or duplicate handling but not necessary.

Agents need to know what a tool does to the 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 well-structured with clear sections, front-loaded purpose, and every sentence adds value. Not overly verbose.

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

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

Given the complexity (single param that is an object with sub-properties) and presence of an output schema, the description provides a complete workflow, examples, and return details. Sufficient for an agent to understand and use the tool.

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

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

Schema already has descriptions for all parameters (name, workspace_id, definition_id, configuration, response_format). Description adds extra context with workflow steps and an example, enhancing understanding, especially for the open-ended configuration object.

Input schemas describe structure but not intent. Descriptions should explain 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 'Create a new destination connector' with a verb and resource. Explains what a destination is and distinguishes from sibling tools like airbyte_create_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?

Explicitly provides 'When to Use' section with two specific scenarios and a 'Recommended Workflow' that references other tools (list_destination_definitions, get_destination), giving clear guidance and 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 readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate those. It adds behavioral context by noting the return value and suggesting a workflow, but doesn't explicitly address potential side effects (e.g., credential storage, costing) or describe the creation behavior beyond the basic fact.

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

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

The description is well-structured with clear sections (introduction, when to use, workflow, returns, examples). It is somewhat lengthy but each part serves a purpose. The front-loaded purpose sentence is 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 the tool's complexity (multiple parameters, dynamic configuration schema) and the presence of an output schema (so return format isn't needed in description), the description covers all essential aspects: purpose, usage guidance, workflow, parameter meaning via examples, and return value. It references sibling tools appropriately.

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

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

Despite the context stating 0% schema description coverage, the actual input schema includes descriptions for most parameters (name, workspace_id, definition_id, configuration, secret_id). The description adds value beyond the schema by providing an example with typical fields and a workflow hint to look at existing sources for configuration 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?

The description explicitly states 'Create a new source connector in Airbyte' and explains what a source is (a data source like database, API, etc.). It distinguishes from sibling tools like airbyte_list_sources or airbyte_update_source by focusing solely on creation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'When to Use' section provides two clear use cases (set up new source, automate provisioning). It also includes a recommended workflow with steps referencing sibling tools, but lacks explicit when-not-to-use or alternative tools that might be more appropriate in some 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?

The annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds the return value ('The created tag with its tagId') and an example, but does not disclose other behavioral aspects like permissions or side effects beyond creation. It does not contradict the annotations.

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

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

The description is concise, well-structured with clear sections (title, When to Use, Returns, Example), and uses fewer than 50 words. Every sentence is informative without redundancy.

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

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

Given the tool's simplicity (one required param, one optional, with output schema), the description provides purpose, usage guidance, return value, and an example. It lacks mention of any prerequisites or error handling, but is largely complete for basic use.

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

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

Schema description coverage is 0% according to context, yet the description only provides an example for the 'name' parameter and does not explain the 'response_format' parameter. The schema itself describes 'name', but the description adds minimal value beyond that. More parameter explanation 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 'Create a new tag in Airbyte.' and adds that it is used to 'Add a new organizational label for resources.' This is a specific verb (create) and resource (tag), and it distinguishes from siblings like airbyte_delete_tag or airbyte_update_tag.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'When to Use' section explicitly says 'Add a new organizational label for resources.' This provides clear guidance on when to invoke the tool. However, it does not mention when not to use it or alternatives.

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

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

Annotations already indicate destructive= and idempotentHints. The description adds crucial detail: 'This is a permanent operation. The tag will be removed from all resources it was attached to.' 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 concise: a single-line statement, a usage guideline, and an example. No superfluous text.

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

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

For a simple delete tool with one parameter and an output schema, the description covers purpose, effect, usage context, and example thoroughly.

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

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

The schema has a nested parameter with some description. The description adds an example UUID format, but most parameter semantics are already clear from 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 'Delete a tag by its UUID', providing a specific verb and resource. It distinguishes from sibling tools like create_tag or update_tag.

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

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

It includes a 'When to Use' section with a clear example: 'Remove an obsolete or duplicate tag.' This is helpful but could be more explicit about 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds efficiency details, truncation behavior, and return format (JSON, structured). Adds value 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?

Well-structured with sections and bullet points. Front-loaded with main purpose, then usage guidelines, return description, and examples. Slightly verbose but 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?

Tool has 3 params, no nested objects, and an output schema. Description covers return format, truncation, contrasts with siblings, and provides examples. Complete and self-contained.

Complex tools with many parameters or behaviors need more documentation. 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 already describes parameters well (100% coverage). Description adds examples and explains when to use tail_lines, providing context beyond schema. Baseline 3 plus 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?

Clearly states it gets logs for a specific attempt of a job, mentions the internal API endpoint, and distinguishes from sibling airbyte_get_job_logs. Specific verb+resource with scope.

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

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

Explicit 'When to Use' and 'When NOT to Use' sections, naming specific alternatives (airbyte_get_job_logs, airbyte_get_cloud_sync_logs). Provides clear context for selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by noting it uses the Airbyte Cloud Config API (POST /jobs/get) and returns plain text with pagination metadata and a JSON object with specific fields. This provides additional transparency beyond annotations, though the safety profile is already well-covered.

Agents need to know what a tool does to the 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 yet comprehensive: a brief summary, technical note, usage sections, return field list, and examples. It is well-structured and front-loaded with the main purpose, making it easy for an AI agent to quickly grasp the tool's function.

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

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

Given the tool's complexity (multiple optional parameters, pagination, Cloud vs self-managed), the description covers purpose, usage conditions, alternatives, return format, and examples. The output schema exists (as indicated), so return value explanation is sufficient. The description is complete for an AI agent to select and invoke the tool correctly.

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

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

The input schema has detailed descriptions for all parameters, so schema_description_coverage is high (despite the context signal saying 0%, the schema shows descriptions). The description adds examples of parameter usage, which is helpful but not essential. With high schema coverage, the baseline is 3, and the description does not significantly add 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 'Get full-text sync logs for an Airbyte Cloud connection job attempt,' specifying the verb, resource, and scope. It distinguishes itself from sibling tools airbyte_get_job_logs and airbyte_get_attempt_logs by noting it is the 'Cloud parity path' for Airbyte Cloud, whereas the siblings are for self-managed deployments.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 explicit 'When to Use' and 'When NOT to Use' sections, providing clear context: use on Airbyte Cloud for raw log text with pagination, avoid on self-managed deployments or when structured failure metadata is needed (use airbyte_get_job_details instead). This gives strong usage guidance and 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=true and destructiveHint=false. Description adds behavioral details: returns the 'most detailed view', error handling (404 if not found), and response format options (markdown/json). 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-organized with distinct sections (overview, when to use/not use, return details, examples, error handling). Each sentence is informative and there is no redundancy. Front-loaded with core purpose.

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

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

Given the tool's simplicity and existing output schema, the description covers all necessary context: what it returns (connection details, streams, sync modes), how to use it (examples with parameters), error behavior, and relationship 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?

Input schema has 1 required parameter (connection_id) with minimal description. The description adds meaning by explaining it as a UUID, providing examples of usage, and mentioning the optional response_format parameter with its two possible values and default.

Input schemas describe structure but not intent. Descriptions should explain non-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 'Get full details of a single connection by its UUID.' and defines the resource (connection) and action (get details). It distinguishes from siblings like airbyte_list_connections and airbyte_get_job.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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' and 'When NOT to Use' sections with clear alternatives (airbyte_list_connections, airbyte_get_job, airbyte_list_jobs). Provides specific use cases for inspection, debugging, and verification.

Agents often have multiple tools that could apply. Explicit usage 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, destructiveHint, idempotentHint. Description adds valuable context: secrets are masked, 404 error handling, and response format details. 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?

Well-structured with headings (overview, when to use/not use, returns, examples, error handling). Slightly lengthy but every section adds value; no redundant 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?

Covers purpose, usage guidance, error handling, response format, and examples. Output schema exists, so return structure is documented elsewhere. Complete for a read 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 has 2 params (destination_id, response_format) with 0% coverage, but description explains destination_id as UUID, response_format as enum (markdown/json), and includes examples. Fully compensates for lack of 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?

Description clearly states 'Get full details of a single destination connector by its UUID' and lists returned fields (name, type, workspace, etc.). Differentiates from sibling tools like airbyte_list_destinations and airbyte_list_jobs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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' and 'When NOT to Use' sections with specific alternative tools (airbyte_list_destinations, airbyte_list_jobs). Provides clear decision guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by detailing the return content (name, Docker image, connector specification), which is not captured in annotations. No contradictions.

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

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

The description is concise and front-loaded with purpose. It uses clear sections ('When to Use', 'Examples') to organize information. While efficient, it could be slightly more structured by explicitly listing the return fields.

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

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

Given the simple tool (3 parameters, one optional) and the presence of a output schema (indicated), the description covers the main points: purpose, return content, and usage context. It lacks parameter details but is otherwise complete for the agent's needs.

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

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

Schema description coverage is 0%, so the description should compensate. However, it only provides an example with workspace_id and definition_id, but does not describe the parameters individually. The optional response_format parameter (with enum default) is not mentioned at all. This is insufficient for an agent to understand parameter 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 'Get details of a specific destination connector definition' with a specific verb and resource. It distinguishes from sibling tools like airbyte_get_source_definition and airbyte_get_destination by focusing on connector definitions. The examples reinforce the purpose.

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

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

The 'When to Use' section provides two specific use cases: inspecting what a connector provides and checking Docker image version. This gives clear context for when to invoke the tool. However, it does not explicitly mention when not to use it or alternative tools like list_destination_definitions.

Agents often have multiple tools that could apply. Explicit usage 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, destructiveHint, idempotentHint), the description discloses return fields (status, type, connection, duration, metrics) and error handling (404 for missing ID), adding valuable behavioral context without contradiction.

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

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

The description is well-structured with clear sections, front-loads the main purpose, and each sentence adds value. Slightly verbose but appropriate for the detail level.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 and comprehensive annotations, the description covers all necessary context: purpose, usage, parameters, return values, examples, and error handling. Complete for an agent to use correctly.

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

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

Though schema description coverage is reported as 0%, the description provides example usage and clarifies that job_id is a numeric ID as string and response_format has a default. This adds practical semantics 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 'Get full details of a single sync or reset job by its numeric ID,' specifying the verb, resource, and method. It also distinguishes itself from sibling tools like airbyte_list_jobs and airbyte_get_connection.

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

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

The description includes dedicated 'When to Use' and 'When NOT to Use' sections with four use cases and two exclusions that name alternative tools, providing explicit guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), description reveals it uses internal Configuration API (POST /v1/jobs/get), works for ALL job types, and returns richer data than public API. 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?

Well-structured with clear headings and bullet points. Concise yet comprehensive, every sentence adds value. Efficient 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 simplicity (one required parameter), presence of output schema, and comprehensive annotations, the description covers all necessary aspects: purpose, usage guidance, return value summary, and alternatives.

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

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

With 0% schema description coverage (per context), the description only provides an example parameter object but no explicit explanation of job_id or response_format fields. Partially compensates but could be more thorough.

Input schemas describe structure but not intent. Descriptions should explain 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 gets detailed job information with per-attempt stats and failure reasons, using internal API. Distinguishes from sibling tools like airbyte_get_job (public API) and airbyte_get_job_logs by noting the richer data and specific use case.

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

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

Contains explicit 'When to Use' and 'When NOT to Use' sections, listing concrete scenarios (e.g., job failure analysis, per-stream stats) and alternative tools per case. Includes a parameter example.

Agents often have multiple tools that could apply. Explicit usage 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 that it always returns JSON with specific fields, logs can be large, and explains tail_lines/attempt_number behavior. 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?

Well-structured with sections, front-loaded purpose, and no redundancy. Slightly lengthy but 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?

Covers purpose, usage, parameters, output format, examples, and alternatives. Output schema exists, so return value details are acceptable. Fully adequate for this 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?

Although schema descriptions exist, the description adds context via examples and explains default/limit behavior for tail_lines and attempt_number. This supplements the schema well.

Input schemas describe structure but not intent. Descriptions should explain non-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 gets log output for a job's sync attempts. It specifies the verb 'get' and resource 'log output', and distinguishes itself from siblings like airbyte_get_job_details and airbyte_get_cloud_sync_logs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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' and 'When NOT to Use' sections provide clear guidance, including alternatives for structured failure info and Airbyte Cloud usage.

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

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

Discloses secret masking, 404 error handling, and response format options. Annotations already declare safety, and the description adds relevant behavioral context 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?

Well-structured with sections, but some redundancy (e.g., 'Returns' repeats earlier info). Still efficient and easy to read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 purpose, parameters, return values (with output schema present), error handling, and usage guidance completely.

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

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

Despite 0% schema coverage, the description explains both parameters (source_id and response_format) with examples and default values, effectively compensating.

Input schemas describe structure but not intent. Descriptions should explain non-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 retrieves full details of a single source connector by UUID, and lists returned fields. It distinguishes from sibling tools like airbyte_list_sources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'When to Use' and 'When NOT to Use' sections, with alternatives such as airbyte_list_sources and airbyte_list_jobs.

Agents often have multiple tools that could apply. Explicit usage 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, which cover the tool's safety profile. The description adds that it returns the 'full definition' with specific fields, providing some context about the response. However, it does not discuss error handling, pagination, or behavior on missing IDs. With annotations providing the core behavioral traits, the description adds moderate value.

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

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

The description is three short sections: a clear opening sentence, a bulleted 'When to Use', and a code example. Every sentence serves a purpose, with no redundancy. It is front-loaded with the main action and structured for quick scanning by an AI agent.

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

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

Given the tool's simplicity (read-only lookup, two required params) and the presence of annotations and an output schema, the description covers the main purpose and provides usage scenarios. It lacks mention of the optional response_format parameter and error cases, but these are minor gaps for a straightforward 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% per context, but the actual schema has descriptions for workspace_id and definition_id. The tool description includes a code example with these parameters but does not explain them or the optional response_format. Since the schema itself provides basic descriptions, the example adds marginal value, earning a baseline 3.

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

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

The description clearly states the tool retrieves details of a specific source connector definition, using the verb 'Get'. It specifies the resource ('source connector definition') and lists what is returned (name, Docker image, connector specification). This distinguishes it from sibling tools like airbyte_list_source_definitions (which lists all) and airbyte_get_source (which gets an instance).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'When to Use' section provides two explicit scenarios: inspecting a specific connector and checking the Docker image version. While it does not exclude alternatives like using the list tool first, it gives clear context for when to invoke this tool. No explicit 'when not to use' or comparison with siblings, but the guidance is focused 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 provide readOnlyHint, idempotentHint, etc. The description adds context about cache bypass and destination-based refinement, which goes 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?

Well-structured with sections, but slightly lengthy. Front-loaded with core purpose. Every sentence adds value, 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 annotations and output schema (present), description covers return format, use cases, and examples. Fully adequate for a 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 provides descriptions for all parameters (source_id, destination_id, ignore_cache). Description adds example usage but does not significantly deepen semantic understanding beyond schema. Baseline 3 due to high schema coverage.

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

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

The description clearly states 'Get the available streams and their properties for a source' and lists specific returned fields (sync modes, cursor field, primary key). This distinguishes it from siblings like airbyte_get_connection, which shows configured streams.

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

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

Includes explicit 'When to Use' and 'When NOT to Use' sections. 'When NOT to Use' directs to airbyte_get_connection for configured streams, providing clear alternative.

Agents often have multiple tools that could apply. Explicit usage 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, destructiveHint, idempotentHint. The description adds error handling details (404, 403) and return format options, which go 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?

Well-structured with clear sections (When to Use, Returns, Examples, Error Handling). Every sentence is informative. No redundancy or fluff.

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

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

With output schema present, description handles return values correctly. Covers error cases and usage context. Complete for a simple get operation with rich 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 has descriptions for workspace_id and response_format. The description adds value by explaining the effect of response_format (markdown vs JSON) and providing examples. It compensates for any schema description gaps.

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

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

The description clearly states it gets full details of a single Airbyte workspace by UUID, with specific verb 'Get' and resource 'workspace'. It distinguishes from sibling tool 'airbyte_list_workspaces' which is for browsing.

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

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

Explicitly provides when to use (look up workspace properties, confirm ID) and when not to use (browsing → use list_workspaces). This is a clear usage guideline.

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

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

Annotations already declare readOnly, non-destructive, idempotent. Description supplements with HTTP method (GET /health), lightweight nature, and details of success/failure output, adding 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?

Description is well-structured with clear sections (purpose, behavior, when to use, return, example, related tools). No redundant sentences, and every part adds value.

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

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

For a simple health check tool with rich annotations and output schema, the description covers all necessary aspects: purpose, usage guidance, expected return, error handling, and relation to other 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?

Input schema has zero parameters, so schema coverage is 100%. Description reinforces that no parameters are needed and provides an example call. No further semantics required.

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

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

The description clearly states the tool checks Airbyte API reachability and health using a specific verb and resource. Among siblings, no other tool serves this purpose, so it stands out.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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' section lists specific scenarios (verify instance, diagnose errors, confirm credentials). Also advises using it as the first call and suggests related tool after (airbyte_list_workspaces).

Agents often have multiple tools that could apply. Explicit usage 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, openWorldHint=true. The description adds behavioral context: pagination with limit/offset defaults, ability to include deleted connections, and response format options (markdown/json). 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 well-structured with clear sections (definition, when to use/not use, return info, pagination, examples). It is concise yet comprehensive, with every sentence adding value. No fluff.

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

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

Given the tool's complexity (multiple parameters, pagination, response formatting), the description covers purpose, parameters, behavior, and examples adequately. It lacks explicit error handling or empty result handling, but for a read-only list tool with good annotations, this is sufficient. The presence of an output schema (not shown) further reduces the need for return value details in the description.

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

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

The input schema's top-level 'params' parameter lacks a description, resulting in 0% schema coverage. However, the tool description compensates by explaining each sub-parameter (workspace_ids, limit, offset, include_deleted, response_format) with defaults and usage examples. While the schema's inner descriptions are good, the description adds contextual guidance (e.g., 'Omit to list across all allowed workspaces').

Input schemas describe structure but not intent. Descriptions should explain non-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 lists connections (source-to-destination pipelines) and defines the concept. It distinguishes from siblings like airbyte_get_connection for a single connection and airbyte_list_jobs for checking runs, making the purpose unambiguous.

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

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

The description includes explicit 'When to Use' and 'When NOT to Use' sections, suggesting specific scenarios like discovering pipelines or finding UUIDs, and directs to alternatives (e.g., airbyte_get_connection for details, airbyte_list_jobs for running status).

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds useful details about the return value (name, definition ID, Docker image), which goes beyond the annotations.

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

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

The description is well-organized with clear sections (purpose, when to use, returns, examples). Every sentence adds value and is free of 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?

Given the tool's simplicity, clear annotations, and existence of an output schema, the description fully covers what an agent needs: purpose, usage context, return fields, and an example. No gaps.

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

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

Schema description coverage is 0%, but the description implicitly covers workspace_id by showing it in the example. However, it omits the response_format parameter entirely, which is documented in the schema but not explained in the description. Thus, only partial compensation.

Input schemas describe structure but not intent. Descriptions should explain non-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 lists destination connector definitions, distinguishing it from airbyte_list_source_definitions and airbyte_get_destination_definition. It also explains the purpose of definition IDs for creating destinations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'When to Use' section provides explicit scenarios: finding definition IDs before creating a destination and auditing custom connectors. It does not explicitly list when not to use, but the context is clear enough.

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

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

Adds significant context beyond annotations: pagination details, return format options, soft-deleted inclusion, and examples. No contradiction with readOnlyHint, destructiveHint, idempotentHint.

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

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

Well-structured with sections, bullet points, code examples. Every sentence adds value; no fluff. Efficiently front-loaded with purpose and when-to-use.

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

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

Comprehensive given 1 required param, optional params, output schema, and annotations. Covers list tool expectations: pagination, filtering, formatting, and example usage.

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

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

Despite schema description coverage 0%, the description explains each parameter (workspace_ids, limit, offset, include_deleted, response_format) with context and examples, compensating fully.

Input schemas describe structure but not intent. Descriptions should explain 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 destination connectors configured in Airbyte.' Distinguishes from siblings like airbyte_get_destination and airbyte_get_destination_definition by scope and output granularity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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' and 'When NOT to Use' sections, providing specific alternative tools (airbyte_get_destination, airbyte_list_connections, airbyte_list_jobs) and clear 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 indicate read-only, idempotent behavior. The description adds operational details like job tracking, version constraints for job types, and pagination behavior, which are not covered by annotations.

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

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

Well-organized with clear sections, front-loaded summary, and no wasted text. Every sentence serves a purpose, from usage guidance to examples.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 filters, pagination, version dependencies, response formats), the description is remarkably complete, covering all key aspects without relying solely on the output schema.

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

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

Although the input schema has parameter descriptions, the tool description adds richer context for each filter (e.g., job_type version notes, created_at_start format), and provides usage examples, significantly enhancing 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 it lists sync, reset, refresh, and clear jobs with rich filtering, and distinguishes from siblings like airbyte_get_job and airbyte_list_jobs_internal.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'When to Use' and 'When NOT to Use' sections with concrete scenarios and references to alternative tools, plus details on filters and pagination.

Agents often have multiple tools that could apply. Explicit usage 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 use of internal Configuration API, pagination, per-attempt stats, config types filter. Annotations already declare readOnly, idempotent, non-destructive; description adds meaningful context 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?

Well-structured with clear sections: overview, when to use/not use, config types, returns, examples. Concise at ~200 words, 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?

Comprehensive for a list tool with output schema. Covers purpose, usage criteria, parameter details, return structure, and examples. No gaps given the complexity and available structured fields.

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

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

Schema has descriptions for all parameters (high coverage), but the tool description adds value by explaining config_types common values and providing examples with parameter usage. Baseline 3, +1 for practical usage guidance.

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

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

Clearly states it lists ALL job types via internal API, explicitly distinguishing from sibling airbyte_list_jobs which only returns sync/reset. Specific verb 'list', resource 'jobs', and scope 'all 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 provides when-to-use (checking refresh/clear jobs, complete history) and when-not-to-use (Airbyte Cloud, only sync/reset needed). Names alternatives airbyte_get_cloud_sync_logs and airbyte_list_jobs.

Agents often have multiple tools that could apply. Explicit usage 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, destructiveHint false, idempotentHint true. The description adds that the tool returns a list with name, definition ID, and Docker image info, which is useful 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?

The description is well-structured with sections for purpose, when to use, returns, and examples. It is concise with no wasted sentences, 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 tool's simplicity (list operation with two params, annotations present, output schema exists), the description covers usage context, return content, and provides an example. It could mention that the list is workspace-specific, but it's adequate.

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

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

Input schema has two parameters: workspace_id (with description 'UUID of the workspace') and response_format (enum with default). The description provides an example using workspace_id but does not explain response_format or further detail workspace_id format. With schema description coverage at 0% (though workspace_id has a description), the description adds limited value over 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 lists available source connector definitions in a workspace, explains what source definitions are, and links to creating a source. It differentiates from sibling tools like airbyte_get_source_definition by focusing on listing all definitions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 includes a 'When to Use' section with two scenarios: finding definition IDs before creating a source and auditing custom connectors. It references the sibling tool airbyte_create_source. However, it does not explicitly state when not to use or compare with get_source_definition.

Agents often have multiple tools that could apply. Explicit usage 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, so description is not needed for safety. However, description adds pagination behavior, response format options, and the ability to include deleted sources. No contradictions. Minor gap: no mention of rate limits or error conditions.

Agents need to know what a tool does to the 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 (When to Use, When NOT to Use, Returns, Pagination, Examples). No fluff, every sentence adds value. 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?

Given the sibling tools and parameters, the description is complete. It explains return fields (name, sourceId, etc.) and pagination. An output schema exists but description covers what the agent needs.

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

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

Despite low schema description coverage (0%), the tool description thoroughly explains parameters: limit (1-100, default 20), offset (default 0), workspace_ids, include_deleted, response_format. Examples show typical usage. Compensates fully for missing 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?

Description clearly states 'List source connectors configured in Airbyte' and distinguishes from siblings like airbyte_get_source, airbyte_list_connections, and airbyte_list_jobs. It is specific about what the tool does and the resource.

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

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

Has explicit 'When to Use' and 'When NOT to Use' sections, providing clear context. It tells when to use this tool (discover sources, find UUIDs) and when to use alternatives (get_source, list_connections, list_jobs). Examples further clarify usage.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that it returns a list of tags with name and tagId, which is useful behavioral context. 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?

Well-structured with clear sections and bullet points. Front-loaded with the main purpose. Could be slightly more concise, but overall 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 the tool's simplicity (one optional param, output schema indicates list of tags), the description covers the return value adequately. Missing details about parameter behavior, but still fairly complete for a list operation.

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

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

The input schema has one optional parameter (response_format with enum markdown/json), but the description does not mention it. With 0% schema description coverage, the description should compensate by explaining available options, but it does not.

Input schemas describe structure but not intent. Descriptions should explain non-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 all tags in Airbyte' and explains what tags are, distinguishing this readonly tool from sibling like create_tag, delete_tag, and update_tag.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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' section with two bullet points provides clear context for when to invoke this tool. Could be improved by also noting when not to use it, but the guidance is helpful.

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

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

The description adds value beyond annotations by explaining pagination (limit, offset, response headers), return format options (markdown/json), and the relationship of workspaces to other entities. No contradiction with annotations (readOnlyHint, etc.).

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

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

The description is well-structured with clear sections, front-loaded with purpose, and uses efficient language. Every sentence serves a purpose without redundancy.

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

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

Given the presence of an output schema and thorough parameter descriptions, the description sufficiently covers pagination, return values, and usage context. It provides all necessary information for correct tool 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 high (all parameters have descriptions). The description provides examples (e.g., limit=5, include_deleted=true) that add practical context beyond the schema, justifying a score above baseline 3.

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

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

The description clearly states 'List all Airbyte workspaces' with a specific verb and resource. It distinguishes from sibling 'airbyte_get_workspace' by noting that this tool is for discovery and listing all workspaces.

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

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

Includes explicit 'When to Use' and 'When NOT to Use' sections, with guidance on when to use 'airbyte_get_workspace' instead. Provides specific use cases like discovering workspace IDs and auditing configuration.

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

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

The annotations already convey destructiveHint=true and readOnlyHint=false. The description adds significant behavioral context: it resets cursors, does not re-read from source (requires a subsequent sync), requires a self-managed Airbyte deployment with direct API access, and is not available on Airbyte Cloud. These details go 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 efficiently structured with a clear opening action, separated sections for usage guidance, and concrete examples. Every sentence serves a purpose, and the most critical information (what the tool does and when to use it) is front-loaded. It is concise yet comprehensive.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (destructive operation on Airbyte), the description covers prerequisites (self-managed deployment, direct API access), constraints (not on Cloud), behavioral implications (no re-read, need subsequent sync), return value (job with ID and status), and provides examples. The presence of an output schema reduces the need to describe return format, and the description meets the completeness bar for an agent to safely invoke the tool.

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

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

The input schema has descriptive comments for each parameter (e.g., stream name, namespace, connection_id). The description reinforces this with practical examples showing exact parameter usage for single and multiple streams. Although the description does not systematically list all parameters, the examples and context (e.g., 'Each needs at least a name') 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 the tool 'clear destination data for one or more streams in a connection,' using a specific verb (clear) and resource (streams in a connection). It distinguishes itself from the sibling airbyte_trigger_refresh by explaining that a clear removes data and does not re-read source, unlike a refresh.

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

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

The description provides explicit guidance on when to use the tool (remove stale data, prepare for clean re-sync, clear after schema changes) and when not to use it (Airbyte Cloud, if re-read without deleting, if connection is running). It also names the alternative tool airbyte_trigger_refresh.

Agents often have multiple tools that could apply. Explicit usage 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 it requires a self-managed Airbyte deployment, explains the refresh process (re-reads, swaps/merges on success, no downtime), and mentions waiting for running jobs. These details go beyond the annotations' destructiveHint and readOnlyHint.

Agents need to know what a tool does to the 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 clear headings for usage, refresh types, return value, and examples. Every sentence adds value, and the core purpose is stated upfront.

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

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

Covers all necessary context: tool purpose, prerequisites (self-managed), usage scenarios, refresh type options, and return format. The presence of an output schema further completes the picture.

Complex tools with many parameters or behaviors need more documentation. 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 beyond the input schema by explaining refresh types ('merge' vs 'truncate') with behavioral differences and providing concrete examples for single and multiple streams, plus enumeration of valid values.

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

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

The description clearly states the tool triggers a refresh for streams in a connection, distinguishing it from siblings like airbyte_trigger_sync (reset) and noting it uses the internal Configuration API, not available on Cloud.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 lists when to use (data gaps, reconcile stale rows, corrected source) and when not to use (on Airbyte Cloud, if reset is acceptable, if connection is busy), with a suggested alternative (airbyte_trigger_sync with reset).

Agents often have multiple tools that could apply. Explicit usage 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 explains that reset clears destination data and causes downtime, while sync does not. It states the return value (newly created job with jobId and initial status). Annotations already indicate readOnlyHint=false, and the description adds behavioral context beyond that.

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

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

The description is well-structured with clear sections, examples, and warnings. Every sentence adds value; there is no redundancy or fluff.

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

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

Given the tool's complexity (two job types, comparison to refresh), the description is very complete. It covers when to use, when not to use, behavioral effects, and return value. The presence of an output schema means return format details are already handled.

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

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

Although the input schema provides descriptions for job_type and connection_id, the description adds meaning by explaining the difference between sync and reset, and provides examples showing how to pass the parameters. The 'When NOT to Use' section also clarifies the job_type parameter's role in deciding between reset and refresh.

Input schemas describe structure but not intent. Descriptions should explain non-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 triggers a sync or reset job for a connection. It distinguishes between sync and reset, and also differentiates from the sibling tool airbyte_trigger_refresh, which is used for non-destructive refreshes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 explicit 'When to Use' and 'When NOT to Use' sections. It advises against using when the connection is already running (and suggests checking with airbyte_list_jobs) and recommends airbyte_trigger_refresh for non-destructive refreshes instead of reset.

Agents often have multiple tools that could apply. Explicit usage 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=false (mutation) and destructiveHint=false. Description adds PATCH semantics (only provided fields change) and mentions return value. 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?

Well-structured: brief intro, PATCH note, 'When to Use' list, recommended workflow, 'Returns', and examples. Every sentence is relevant and concise.

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

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

Given rich input schema descriptions and presence of output schema, description covers all key aspects: purpose, usage guidance, workflow, and examples. Complete for an update 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% but input schema has descriptions for each parameter. The description provides no parameter details but gives examples showing how to use status and schedule, adding some value. Adequate but not fully compensatory.

Input schemas describe structure but not intent. Descriptions should explain non-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 'Update an existing connection's configuration' and specifies PATCH semantics. It distinguishes itself from siblings like airbyte_create_connection (creation) and airbyte_get_connection (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?

Explicitly lists when to use (change schedule, enable/disable, add/remove streams, update namespace/prefix) and provides a recommended workflow with three steps. Also includes examples for common use cases.

Agents often have multiple tools that could apply. Explicit usage 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 idempotentHint=true and destructiveHint=false. Description adds 'Uses PATCH semantics: only the fields you provide are changed,' which clarifies the update behavior. No contradiction.

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

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

Description is well-structured with sections, front-loaded with purpose, and every sentence adds value. 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?

Covers purpose, when to use, workflow, behavior, and examples. Although output schema exists but not shown, the description mentions return value. Lacks error handling or auth notes but is sufficient for an update tool with idempotent hint.

Complex tools with many parameters or behaviors need more documentation. 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 detailed descriptions for each field. Description adds value by providing concrete examples (rename, update configuration) and a workflow, which helps the agent understand how to populate parameters. The examples make it a 4.

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

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

Description clearly states 'Update an existing destination connector's name or configuration.' It specifies the action, resource, and scope. It distinguishes from sibling tools like airbyte_create_destination and airbyte_get_destination by focusing on updating an existing entity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 includes a 'When to Use' section with three clear scenarios and a recommended workflow (get, build, update). It provides context but does not explicitly mention when NOT to use or list alternatives; however, the guidance is strong.

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

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

Annotations already indicate idempotentHint=true and non-destructive, but the description adds critical behavioral details: 'Uses PATCH semantics: only the fields you provide are changed. The configuration object is merged at the top level by the API.' This goes beyond annotations and is essential for correct invocation.

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

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

The description is well-organized into clear sections: main purpose, PATCH semantics, when to use, recommended workflow, return value, and examples. Every sentence earns its place, and there is no redundant information.

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

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

Given the complexity of a PATCH update with merging behavior, the description is complete. It covers what the tool does, how it behaves, prerequisites (get source first), and expected outcomes. The presence of an output schema further reduces ambiguity.

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

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

Even though the input schema already describes parameters, the description adds significant value by explaining the merge behavior and providing concrete examples (rename and update config). This helps an agent understand how to construct the configuration object correctly.

Input schemas describe structure but not intent. Descriptions should explain non-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 updates an existing source connector's name or configuration, using specific verb and resource. It differentiates it from sibling update tools like airbyte_update_connection or airbyte_update_destination by focusing on sources.

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

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

The description provides explicit 'When to Use' bullet points (change credentials, rename, update settings) and a 'Recommended Workflow' with three steps. It does not explicitly state when not to use, but the context given is sufficient for an agent to decide.

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

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

Annotations already indicate idempotentHint=true and readOnlyHint=false, so the description adds value by stating the return value. 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 concise with two main sentences plus an example. Information is front-loaded and no unnecessary text.

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

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

The tool is simple (rename a tag) and the description covers purpose, usage, and return value. With output schema present, no further details are needed.

Complex tools with many parameters or behaviors need more documentation. 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%, meaning the description does not elaborate on parameters. The schema itself provides brief descriptions for tag_id and name, but the description adds no additional meaning or guidance for using 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 description clearly states 'Update an existing tag's name', specifying the verb (update) and resource (tag name). It distinguishes from sibling tools like airbyte_create_tag and airbyte_delete_tag.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'When to Use' section provides clear context: 'Rename a tag for better organization.' While it doesn't explicitly state when not to use, the purpose is straightforward and no alternative tool is 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 already declare readOnlyHint=true and idempotentHint=true, so no contradiction. Description adds valuable behavioral context: uses POST /jobs/get, polls until succeeded/failed/cancelled/incomplete or timeout, returns final summary or timeout message. No missing critical 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?

Concise and well-structured with clear sections (intro, when to use/not use, returns, examples). Every sentence adds value with no repetition or fluff.

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

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

Tool is a polling wrapper with timeout; description covers purpose, usage, constraints, return behavior, and examples. Output exists (implied by 'Returns final job summary'), but not detailed. Still complete for the tool's complexity.

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

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

Input schema has 100% description coverage for all four parameters (job_id, response_format, max_wait_seconds, poll_interval_seconds). Description adds no additional parameter semantics beyond examples, so baseline 3 applies.

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

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

Description clearly states 'Poll an internal job until it reaches a terminal status.' It uses specific verb (poll) and resource (internal job), and distinguishes from siblings like airbyte_get_job_details which is a one-shot check.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 sections for when to use (after trigger_refresh/trigger_clear) and when NOT to use (for one-shot status check or on Airbyte Cloud). Also names alternative tool airbyte_get_job_details.

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