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

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false and readOnlyHint=false, so safety framing is covered. The description adds two useful non-annotation traits: that it validates before creating and that it 'may copy source data' (a data-movement/cost implication). It still omits permission requirements, reversibility, and rate limits, so it adds some but not rich context.

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

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

Two short, front-loaded sentences with no filler; the core action leads. It is arguably too terse for a complex mutation tool, but the text itself is efficient and well-ordered.

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

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

For a destructive, open-world mutation tool with a deeply nested config and 0% schema description coverage, the two-sentence description is insufficient. The output schema means return values need not be covered, but the near-total absence of parameter and behavioral detail leaves significant gaps.

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

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

Schema description coverage is 0% and the single 'config' parameter is a large nested CDCConfig object with many meaningful fields (do_initial_snapshot, table_mappings, snapshot tuning, etc.). The description mentions 'existing peers' and source-data copying but does not explain the config structure or any field semantics, leaving the heavy schema essentially undocumented.

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

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

States a specific verb (create) and resource (CDC pipeline) and adds the prerequisite 'using existing peers', which helps distinguish it from sibling tools like validate_pipeline. However, it does not explicitly contrast itself with validate_pipeline or update_pipeline, so an agent must still infer the boundary.

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

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

'using existing peers' implies a prerequisite (peers must already exist) but the description gives no explicit when-to-use vs when-not guidance, nor does it route the agent to validate_pipeline or update_pipeline. Usage is only implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real value by disclosing that partial results are returned when a check fails and that no repair is attempted. These are behavioral traits not captured by 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?

Two tight sentences with the core diagnostic purpose front-loaded and the failure/read-only caveats following. No filler; every clause carries meaning.

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

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

An output schema exists, so return-format details are not required, and the description covers the key edge case (partial results on failure) plus the non-mutating guarantee. The main remaining gap is that neither parameter is described.

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

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

Schema description coverage is 0% and the description says nothing about either parameter. It never explains what 'name' identifies (pipeline name) or what 'limit' bounds (e.g., error/batch rows), so it fails to compensate for the undocumented schema.

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

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

States a specific verb (diagnose) and resource (pipeline) and clarifies it aggregates status, recent errors, and CDC batches into heuristic troubleshooting. This distinguishes it in substance from the sibling single-fetch tools (get_pipeline_status, get_pipeline_errors, get_pipeline_batches), though it never names them explicitly.

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

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

'Never repairs or changes a pipeline' signals the read-only diagnostic role and implicitly points write actions to update/resume/pause siblings, but there is no explicit statement of when to reach for this aggregate tool versus the granular get_* siblings. Usage is implied rather than spelled out.

Agents often have multiple tools that could apply. Explicit usage 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 disclose that this is a read-only, idempotent, non-destructive, open-world operation. The description adds that the tool checks gateway connectivity, which is useful behavioral context, but it does not provide additional details such as failure modes or rate limits.

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

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

The description is a single, front-loaded sentence with no wasted words. It directly states the two things the tool does.

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

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

Given that the tool has no parameters, rich annotations, and an output schema, the description is nearly complete. It could be slightly improved by explicitly noting that it is a diagnostic ping, but the essential context is present.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain. The baseline for a parameterless tool is 4, and the description appropriately does not attempt to document nonexistent 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 gives specific verbs and resources: it checks gateway connectivity and reports the PeerDB version. This clearly identifies the tool's purpose, though it does not explicitly differentiate itself from sibling pipeline and peer management tools.

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

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

The description implies usage for checking connectivity or retrieving the PeerDB version, but it does not state when to use this tool versus alternatives or when it should be avoided. The context is inferable but not explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds useful context that it is PostgreSQL-specific and that it targets source peers rather than destinations, but it says nothing about auth requirements, behavior on a non-source peer, or rate limits.

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

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

A single tight sentence with the verb and resource front-loaded and zero filler. Nothing in it is redundant with the schema or annotations.

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

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

The tool is a simple read-only single-parameter call and an output schema exists, so return values need no explanation. What is inspected is clear; only the edge case of calling it against a non-source peer is left unaddressed.

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

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

Schema description coverage is 0% for the single peer_name parameter, and the schema provides only a pattern and length bounds, no meaning. The description partially compensates by implying the peer must be a source peer, but gives no format, example, or lookup hint for the name.

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

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

The description names a specific verb (inspect) and resource (PostgreSQL replication slots and lag) and scopes it to a source peer, which is more precise than the sibling names like get_pipeline_status. It does not explicitly contrast itself with siblings such as diagnose_pipeline or get_pipeline_errors, so it falls short of full differentiation.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The phrase 'for a source peer' implies a precondition but never states what to do for a destination peer or which sibling to pick when diagnosing replication issues.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile needs no restating. The description only adds that the payload is CDC batch data rather than QRep, and says nothing about cursor/pagination behavior implied by before_id or about volume controls.

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

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

A single compact sentence with the action and resource front-loaded and the QRep exclusion trailing. No filler, though the QRep clause assumes domain familiarity.

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

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

An output schema exists, so return-value explanation is unnecessary, and annotations cover the safety profile. What remains missing is parameter-level guidance for a tool whose schema documents nothing, leaving an agent without direction on how many batches are returned or how to page.

Complex tools with many parameters or behaviors need more documentation. 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 carries the full burden for name, limit and before_id, yet it explains none of them. It does not clarify that 'name' is the pipeline identifier, nor that limit caps batch count or that before_id is a backward pagination cursor.

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

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

States a specific verb+resource (get recent CDC batches) plus the reason for doing so (inspect throughput and sync progress), and scopes out QRep replication. It is distinguishable from siblings like get_pipeline_status or get_pipeline_errors because it targets batch-level CDC data, though no sibling is named directly.

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

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

Gives a clear usage context (throughput and sync progress inspection) and an explicit exclusion ('not for QRep'), which is meaningful guidance. It stops short of naming which tool to use instead for QRep data, so it is not a full when/when-not/alternative statement.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the pagination behavior and the default '20 most recent errors' scope, but that largely restates the schema defaults (limit=20, level=error) rather than disclosing new traits such as ordering or truncation 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?

A single compact clause, front-loaded with the action and the resource, with zero filler. Nothing is over-explained.

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

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

An output schema exists so return values need no prose, but the tool has a required, undocumented `name` parameter and heavy sibling overlap. The description does too little to let an agent invoke it confidently.

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

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

Schema description coverage is 0% across 4 parameters, so the description must compensate and it does not. It hints at pagination and the error default, but the required `name` parameter is never explained—ambiguous given siblings like list_peers and get_peer_slots that also take names.

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

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

States a specific verb (Read) and resource (paginated pipeline logs/errors), so the agent knows this retrieves log entries rather than status or batches. However, it never distinguishes itself from close siblings like diagnose_pipeline or get_pipeline_status, which also touch pipeline failures.

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

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

The description gives no when-to-use guidance and names no alternative. With 12 siblings including diagnose_pipeline, an agent has no signal about when to pull raw error logs versus running a diagnosis.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is fully covered. The description adds the content domains returned (state, config, snapshot progress, totals), but since an output schema exists the return list is partly redundant. It discloses no behavioral traits beyond the structured fields.

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

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

A single front-loaded sentence that names the verb, resource, and returned content areas with zero filler. Appropriately sized for a simple read getter.

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

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

For a read-only status getter with rich annotations and an output schema covering return values, the description is largely complete. The one real gap is guidance on the required 'name' argument and how this tool relates to its overlapping siblings.

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

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

The single required parameter 'name' has 0% schema description coverage, and the description never mentions it or its expected format (e.g., pipeline name vs. ID). The description therefore fails to compensate for the schema gap on a required field.

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

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

States a specific verb ('Get') and resource ('pipeline state') and enumerates what it surfaces: configuration, snapshot progress, replication totals. Clear on its own, but it doesn't distinguish itself from overlapping siblings like get_pipeline_errors, get_pipeline_batches, or diagnose_pipeline.

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

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

No when-to-use, when-not-to-use, or alternative guidance is given. With several siblings returning pipeline-adjacent data (get_pipeline_errors, get_pipeline_batches, diagnose_pipeline), the absence of any routing advice forces the agent to guess which tool answers its question.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered by structured data. The description adds that peers are categorized as source and destination, which is mild extra context, but says nothing about filtering, pagination, or empty results.

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

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

A single front-loaded sentence with no filler; the resource and its scope are stated immediately. Nothing in the sentence is redundant or wasted.

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

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

With an output schema present, the return values need not be described, and the zero-parameter signature and annotations cover the rest. The only shortfall is the lack of differentiation from get_peer_slots, which an agent might reach for instead.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to compensate for. No parameter semantics are needed or missing.

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

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

States a specific verb (list) and resource (peers), and scopes them to source/destination peers used for pipeline configuration. It does not, however, distinguish this from sibling tools like get_peer_slots, which an agent could easily confuse with peer listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 phrase 'for pipeline configuration' implies the context in which this list is useful, but there is no explicit when-to-use guidance and no named alternative among the many pipeline siblings. Usage is only inferable.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered by structured data. The description adds only that the result spans both CDC and QRep pipelines and includes peers and current state, which is modest additional context but not deep behavioral disclosure.

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

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

A single front-loaded sentence with no filler. It conveys the resource, the pipeline types, and the included information in one pass.

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

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

With no parameters, a full annotation set, and an output schema that carries the return structure, the description covers what an agent needs in order to select and invoke the tool. The only missing element is routing guidance toward the more specific sibling tools.

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

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

The tool takes no parameters, so there is nothing for the description to document; the baseline for a zero-parameter tool applies.

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

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

States a specific verb (List) and resource (CDC and QRep pipelines), plus the scope of what is included (peers and current states). It is clear, but it does not differentiate itself from siblings like list_peers or get_pipeline_status, which cover overlapping territory.

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

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

There is no when-to-use guidance, no mention of alternatives such as get_pipeline_status for a single pipeline's state, and no stated preconditions. The agent must infer when this broad listing is preferable to the sibling status/peer tools.

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

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

The annotations already declare non-read-only, destructive, non-idempotent, open-world behavior. The description adds genuine value beyond them by revealing that the call is asynchronous ('request' + poll to observe completion), which an agent must know to avoid treating the return as final. It does not explain the destructive impact on in-flight batches or any permission requirements, so it remains partial.

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

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

Two short sentences, front-loaded with the action and followed by the essential follow-up step. Every clause carries information an agent needs.

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

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

Down-weighted dimension: with an output schema present, return values need not be explained. The remaining gap is behavioral (destructive impact, permission/async semantics depth) which overlaps the transparency score.

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

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

Schema description coverage is 0% and the single required parameter 'name' is never mentioned in the description. The agent gets no hint about whether 'name' is the pipeline name, an ID, or a fully qualified identifier, nor any link between it and the 'running pipeline' being paused.

Input schemas describe structure but not intent. Descriptions should explain 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 specific verb + resource ('pause of a running pipeline') and it implicitly pairs against the sibling resume_pipeline. It stops short of naming that sibling or scoping which pipelines qualify, so it is clear but not fully differentiated.

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

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

'Request pause of a running pipeline' implies the precondition that the pipeline must be running, and 'Poll status to observe completion' points at the get_pipeline_status sibling. However, there is no explicit when-not guidance (e.g., what to do for a paused/stopped pipeline) and the routing advice is indirect.

Agents often have multiple tools that could apply. Explicit usage 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=false, destructiveHint=true, and idempotentHint=false; the description adds the meaningful fact that resume is asynchronous and completion must be observed via status polling. It does not explain why a resume carries a destructive hint, whether it is repeatable, or any authorization requirement.

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

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

Two short sentences, action first, follow-up second, with no filler. Slightly terse for the amount of missing information, but nothing is wasted.

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

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

An output schema exists, so return values need not be described. For a destructive, non-idempotent mutation the description covers the action and the async follow-up but leaves the parameter meaning and failure/authorization behavior unspecified.

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

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

Schema description coverage is 0% and the single required parameter 'name' is undocumented in the schema. The description never clarifies that 'name' identifies the target pipeline, nor any format or naming rules, so it fails to compensate for the coverage gap.

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

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

States a specific verb (resume) and resource (pipeline) with a qualifying scope (paused pipeline), which implicitly separates it from the sibling pause_pipeline. It stops short of explicitly naming or contrasting with the alternative sibling, so it is clear but not fully differentiated.

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

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

The precondition is implied by 'a paused pipeline', and the second sentence gives follow-up guidance (poll status to observe completion). There is no explicit statement of when not to use it or which sibling to prefer for other states.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the mutation profile is covered. The description adds genuine value beyond them: adding tables may trigger snapshots, removing tables stops their replication, and concurrent lifecycle changes should be avoided. It does not address reversibility, which update fields can be left unset, or auth/permission needs.

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

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

Three tight sentences, front-loaded with the operation and followed by preconditions then cautions. Every sentence adds distinct information with no repetition of the schema or annotations.

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

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

For a destructive, non-idempotent mutation with an output schema present, the description adequately covers scope, preconditions, and side effects. The notable omission is whether omitted fields are left unchanged (partial vs. full update) and the role of the required 'name' argument, which an agent needs to call it safely.

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

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

Schema description coverage is 0%, so the description carries the full burden. It names the main field groups (batch size, idle timeout, snapshot settings, table mappings), partially compensating for the undocumented nested CDCUpdate properties. However, it never explains the required 'name' parameter or partial-update semantics for the nested object, so meaningful gaps remain.

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

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

States a specific verb (Modify) and resource scope (CDC batch size, idle timeout, snapshot settings, table mappings), which immediately separates it from siblings like create_pipeline, pause_pipeline, or resume_pipeline. An agent can identify the operation without opening the schema.

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

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

Gives clear preconditions ('Requires running or paused state') and cautions about side effects and concurrency ('avoid concurrent lifecycle changes'), which is strong when-to-use guidance. It does not name an alternative (e.g., pause_pipeline first, or validate_pipeline before applying) or a when-not-to-use case, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond that: it is a dry-run validation that performs no pipeline creation, which explains the read-only behavior and reassures the agent no side effects occur.

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

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

A single front-loaded sentence with zero filler. It is efficient, though for a tool wrapping a large nested config object it is arguably too terse to be 'appropriately sized.'

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

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

An output schema exists, so return values need not be described, and annotations cover safety. However, for a validation tool with a complex required config, the description omits what validation actually checks or what constitutes a failure, leaving the agent with a minimal but workable 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?

Schema description coverage is 0%, so the description carries the burden of explaining the single 'config' parameter, yet it only says 'a CDC configuration.' None of the ~15 CDCConfig fields (source_name, table_mappings, do_initial_snapshot, etc.) are explained, so the description does not compensate for the coverage gap despite the schema's rich 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?

States a specific verb (validate) and resource (CDC configuration) and explicitly bounds scope with 'without creating a pipeline.' This distinguishes it from the sibling create_pipeline without requiring the agent to open either schema.

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

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

The phrase 'without creating a pipeline' effectively names the alternative (create_pipeline) and the when-not condition, giving clear context for selecting this tool. It stops short of stating when validation should be run (e.g., pre-flight before create), so it is not a full 5.

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