Estuary Flow MCP by usefulapi

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

Annotations only supply destructiveHint, so the bar is low; the description adds real behavior: the draft starts empty, it is a staging area, and it does not affect live pipelines. The stated non-impact on production sits in mild tension with destructiveHint=true, but the description itself is behaviorally informative.

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 short sentences with the write semantics front-loaded and no filler. The 'Estuary control-plane: POST /drafts' line is implementation detail of limited value to an agent choosing a tool, a minor inefficiency.

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

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

With no output schema, the description helpfully states 'Returns the created row,' and for a one-optional-parameter creation tool that is nearly everything an agent needs. Only the relationship to publish/upsert siblings remains 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 100% for the single optional 'detail' parameter, so the schema already carries the semantics. The description adds nothing about the parameter, making the baseline 3 appropriate.

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

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

Specific verb (create) plus resource (a new empty draft workspace) with scope clarified as a staging area for catalog changes. It is clearly distinguishable from siblings such as list_drafts, publish_draft, and upsert_draft_spec.

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 useful context (staging area for catalog changes, does not affect live pipelines) that implies when to reach for it, but it never states when to use this versus publish_draft or upsert_draft_spec, nor any prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, and the description adds real context beyond that: the data source (live_specs_ext control-plane view), the underlying PostgREST call with limit=1, and the fact that both the serialized spec and its compiled form come back. It does not say what happens on a non-matching name or whether 'live' excludes unpublished drafts, but it materially enriches the safety-plus-behavior picture.

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 compact sentences with the resource and return payload front-loaded, followed by a short provenance line. The PostgREST endpoint string is arguably implementation detail, but it is brief and plausibly useful for debugging; nothing is padded.

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

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

There is no output schema, so the description correctly compensates by naming the returned fields (spec, built_spec), and the single input is fully documented. The residual gap is failure behavior for an unknown catalog_name and explicit live-vs-draft scope, which keeps it short of a 5.

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

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

Schema coverage is 100% and the single parameter already carries its own description with an example, so the schema does the heavy lifting. The description's restatement of 'exact catalog_name' reinforces strict-match semantics but adds no format, casing, or escaping detail beyond what the schema supplies — 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?

States a specific verb and resource ('Get one live catalog entity') and enumerates what is returned ('full serialized spec and compiled built_spec'). The word 'one' plus 'exact catalog_name' cleanly separates it from estuary_list_catalog and estuary_list_draft_specs, which are the obvious lookalikes among the siblings.

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

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

The exact-name requirement implies this is a point lookup rather than a search, and 'live' hints it is not for drafts. But it never names an alternative (e.g. estuary_list_catalog for discovery or estuary_list_draft_specs for drafts) or says what to do when the exact name is unknown, so the guidance remains implied rather than explicit.

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

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

Annotations only declare readOnlyHint=true, so the description usefully adds the data source (Estuary control-plane view catalog_stats) and the underlying PostgREST call, which helps an agent understand the aggregation model and time-grain semantics. It does not mention auth needs, pagination defaults, or what happens with a nonexistent catalog_name, so it stops short of full 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?

Front-loaded with the core purpose, followed by scope and data-source notes across three tight sentences. The internal view/PostgREST references are arguably dispensable but are compact and aid debugging.

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

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

With no output schema, the description compensates by enumerating the returned metric fields and the per-row grain, so an agent knows what a call yields. It lacks guidance on defaults for date range and result limits, which is a minor gap for a read-only stats tool.

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

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

Schema description coverage is 100%, so all five parameters (grain enum, limit, ts_start/ts_end, catalog_name) are already documented in the schema. The description restates grain and the optional timestamp bound but adds no format or interaction detail beyond that, matching the baseline for high-coverage schemas.

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 (catalog stats) and enumerates the exact metrics returned — bytes/docs read+written, usage_seconds, warnings/errors/failures, txn_count — plus the grain dimension. This clearly distinguishes it from sibling read tools like estuary_get_catalog_spec or estuary_list_catalog.

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

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

The description implies usage context ('Optionally bound by a timestamp range') but never states when to choose this over the catalogue-listing or spec-reading siblings, nor any exclusion or prerequisite. Usage is inferable from the metric list rather than stated.

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, so the safe-read profile is covered structurally. The description adds useful context (which fields come back, that it hits the control-plane tenants table) but says nothing about auth requirements, sensitivity of payment-provider data, or behavior when the user has multiple tenants. Adequate but not rich.

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 compact sentences with the returned-field list front-loaded and no filler. The trailing 'PostgREST: GET /tenants' is implementation detail of marginal value to an agent but costs little.

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

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

With no output schema, the description compensates by naming the returned fields, and readOnlyHint covers safety. Only minor gaps remain (multi-tenant return shape, pagination via limit), which are not critical for a simple read.

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

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

Schema coverage is 100% and the single 'limit' parameter is fully described in the schema, so the baseline of 3 applies. The description adds nothing about the limit/row-cap semantics beyond what the schema already carries.

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 and resource ('Get the user's tenant(s)') and enumerates exactly what is retrieved: quotas, billing tiers, recurring charge, trial start, and payment provider. No sibling tool covers tenants, so the agent can select it unambiguously.

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

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

Usage is only implied — the agent can infer this is the tenant/account-info lookup, but the description never states when to reach for it versus other get/list tools, nor any prerequisites. There is no explicit alternative named, so this lands at minimum viable.

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, so the safety profile is covered; the description adds non-obvious context: results are permission-scoped to what the user can read, and the source is the control-plane view live_specs_ext via PostgREST GET. It stops short of disclosing paging defaults, result caps, or ordering.

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, with the what/scope front-loaded before the optional filters and the backend reference. Every clause carries information, though the raw PostgREST endpoint/table notation is internals an agent rarely needs and is the one bit of low-yield 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?

With no output schema, the description partly compensates by naming the returned payload ('connector + last-publication metadata') and the visibility scope. It still leaves the exact result shape, field set, and default/max limit behavior unspecified, which is a modest gap for a list endpoint.

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

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

Schema description coverage is 100%, so limit, offset, spec_type, and name_prefix are fully documented in the schema (including the like wildcard behavior). The description's mention of prefix and spec_type filtering largely repeats that, adding no syntax or format detail beyond it. Baseline 3 applies.

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

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

The description names a specific verb and resource ('List live catalog entities'), enumerates the entity kinds (captures, collections, materializations, tests), and adds the returned metadata (connector + last-publication). The word 'live' implicitly separates it from the draft-oriented siblings (list_drafts, list_draft_specs) without needing 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?

It states the optional narrowing filters and the read-only visibility scope ('the user can read'), which implies the read path, but never names an alternative tool or states a when-not condition. An agent must infer that single-entity lookups belong to get_catalog_spec and count queries to get_catalog_stats.

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 readOnlyHint annotation already establishes this is a safe read, lowering the burden. The description adds the backing API surface ('PostgREST: GET /connectors') and the catalog scope, but says nothing about pagination behavior despite a limit parameter, nor about catalog size or refresh cadence.

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

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

Front-loaded and reasonably tight, but the trailing fragments ('Estuary control-plane table connectors. PostgREST: GET /connectors.') read as leftover notes rather than useful guidance, and the 'table connectors' phrasing sits awkwardly against a Docker-connector catalog.

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

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

With no output schema, the description usefully discloses what is returned (titles, descriptions, logos) and that the list can be filtered, and the tool is a simple two-optional-parameter read. Complete enough to call correctly, missing only return-volume/pagination context.

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

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

Schema description coverage is 100%, so both limit and recommended are already documented at the schema level. The description's mention of the recommended filter merely restates the parameter and adds no syntax, default, or interaction detail — 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?

States a specific verb and resource ('List the connector catalog') and enumerates the returned fields (titles, descriptions, logos) plus the connector types (capture/materialization Docker connectors). It does not, however, distinguish itself from close siblings such as estuary_list_catalog or estuary_list_connector_versions, so an agent still has to infer which list to call.

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

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

The only usage signal is 'Optionally filter to recommended connectors,' which is implied by the schema anyway. There is no statement of when to prefer this over estuary_list_catalog or estuary_list_connector_versions, and no prerequisites or exclusions are given.

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

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

With only readOnlyHint=true provided, the description carries the rest and does well: it names the return fields (protocol, documentation URL), the backing table connector_tags, and the PostgREST endpoint GET /connector_tags. It stops short of describing pagination or ordering behavior, so it is not fully transparent.

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

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

Front-loaded with the core action and scope in the first clause, then filters, then implementation detail. The trailing table/endpoint notes are meta but arguably earn their place by telling an agent this is a raw PostgREST 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?

For a read-only list tool with no output schema, the description discloses the key returned fields and the underlying endpoint, which is enough for an agent to call it correctly. Only the absence of pagination/ordering guidance keeps it from a 5.

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

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

Schema description coverage is 100%, so both parameters are already documented there and the baseline is 3. The description restates connector_id as an optional filter but adds no syntax or 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?

States a specific verb and resource ('List available versions (image tags) of connectors') and clarifies the ambiguous term 'versions' as image tags. An agent can distinguish it from estuary_list_connectors, which returns connectors rather than their versions.

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 by noting the optional connector_id filter and cross-referencing estuary_list_connectors as the source of that id, but it never states when to reach for this tool versus the sibling list tools or what happens with no filter.

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 supply readOnlyHint=true, so the safety profile is already covered. The description adds that this reads the Estuary control-plane table 'discovers' via PostgREST GET /discovers, which is real backend context, but it omits pagination defaults and result shape 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?

Three compact clauses with the primary purpose front-loaded. The 'Estuary control-plane table discovers' phrasing is mildly redundant with the endpoint note, but nothing is wasteful enough to penalize.

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

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

For a single-optional-parameter, read-only listing tool with no output schema, the description covers what is listed, what a discover means, and the backing endpoint. Only the guidance on alternatives and pagination defaults is missing.

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

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

One parameter with 100% schema description coverage, so the schema already explains 'limit' as the PostgREST max-rows value. The description adds no syntax or default-value detail beyond the schema, which is the baseline case.

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?

Names a specific verb (List) and resource (connector discovery jobs), and the parenthetical explains what a discover is (auto-detecting bindings/resources for a capture). This is far clearer than a name-only restatement, though it does not explicitly distinguish itself from siblings like estuary_list_catalog or estuary_list_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?

No statement of when to use this over competing listing tools, no prerequisites, no exclusions. The purpose is inferable from the parenthetical, but nothing routes the agent between this and the ten other list_* siblings.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds one real behavioral fact — results are scoped to 'the user's' drafts, not all drafts — but the 'Estuary control-plane table drafts' and 'PostgREST: GET /drafts' fragments are implementation trivia that tell an agent nothing actionable. No pagination or ordering behavior is disclosed.

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 short fragments with the core purpose front-loaded, so it reads quickly. The trailing PostgREST endpoint and table-name fragments are near-zero value for an agent and could be dropped without loss.

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 one-parameter read-only list tool this is largely adequate, but with no output schema the description never hints at what a draft record contains (id, name, timestamps) or how results are ordered/paginated. An agent knows what the tool lists but not what it gets back.

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

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

Schema description coverage is 100% and there is only one optional integer parameter, so the schema fully carries the load. The description adds no syntax, default, or range guidance for limit, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('List the user's draft workspaces') and even defines what a draft is ('staging areas for catalog edits before publishing'), which is genuinely clarifying vocabulary. However, it does not differentiate itself from close siblings like estuary_list_draft_specs or estuary_list_publications, so an agent still has to guess which listing matches its intent.

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 parenthetical about drafts being pre-publish staging areas implies the usage context (use this before publish_draft, and to review unpublished work). But there is no explicit when-to-use or when-not-to-use statement, and no routing to alternatives such as list_draft_specs for the contents of a draft.

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?

readOnlyHint=true already establishes the safe-read profile, so the bar is lower. The description adds useful context (backed by the control-plane table draft_specs, PostgREST GET /draft_specs) but says nothing about pagination behavior, ordering, result shape, or auth requirements beyond what the annotation and limit param imply.

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 compact clauses, front-loaded with the core purpose and then the entity definition. The trailing PostgREST/table detail is slightly implementation-flavored but minimal and not wasteful.

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

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

A simple two-parameter read tool with a fully documented schema and no output schema. The description supplies the conceptual meaning of a 'draft spec' and its scope, which is enough for an agent to call it correctly; only return-shape/ordering details are absent.

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

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

Schema coverage is 100%: both draft_id (the draft to list staged specs for) and limit (PostgREST max rows) are fully documented in the schema. The description adds no syntax or format detail beyond that, so the 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?

States a specific verb ('List') and resource ('staged spec entries within a draft') and defines the entity concretely as an insert/replace of a catalog entity pending publication. This scope ('within a draft') distinguishes it from estuary_list_drafts (which lists the drafts themselves) and estuary_get_catalog_spec (a single published spec). An agent can tell what it returns 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?

Usage is implied: you call it with a draft_id to enumerate that draft's staged specs. However, there is no explicit when-to-use vs alternatives guidance, no mention of when the result is empty, and no routing against siblings like estuary_list_publications or estuary_get_catalog_spec.

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

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

With readOnlyHint=true already declaring the safety profile, the description adds genuinely useful context beyond annotations: the outcome semantics of job_status (queued/success/failed), the fact that these are control-plane table rows, and the underlying PostgREST endpoint. It does not cover ordering or pagination behavior, so it falls short of a 5.

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 short fragments, front-loaded with the core purpose and free of filler. The trailing 'PostgREST: GET /publications' is implementation detail that is marginally useful but not strictly necessary.

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

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

For a single-parameter, no-output-schema list tool, the description supplies the missing return-value semantics (job_status values) and the data domain, which is enough for correct invocation. It could still mention ordering or volume expectations but nothing essential is absent.

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?

There is only one optional parameter and schema description coverage is 100%, so the schema already documents 'limit' fully. The description adds no syntax, default, or ordering guidance beyond that, making the baseline 3 appropriate.

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

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

The description names a specific verb and resource ('List publication history/status') and clarifies the unit of a row — 'each publish attempt of a draft' — which separates it from estuary_list_drafts and estuary_publish_draft. It does not explicitly name the sibling that triggers a publish, so it stops 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?

Usage is only implied by the content ('publication history/status') — an agent can infer this is for checking past publish attempts, but there is no explicit when-to-use, when-not-to-use, or pointer to alternatives such as estuary_publish_draft or estuary_list_drafts.

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, so 'Read-only RPC' largely restates structured data. It does add context beyond annotations by naming the control-plane endpoint (POST /rpc/auth_roles), but says nothing about return shape, pagination, or auth failure modes, and no output schema exists to cover that gap.

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 result meaning, with the endpoint detail appended. No filler.

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

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

With only one optional parameter, no output schema, and annotations covering the safety profile, the description gives enough to call it correctly. The return structure (how roles map to prefixes) is only hinted at, which is the main residual gap.

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

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

Schema description coverage is 100% and the single enum parameter (min_capability) is fully documented in the schema. The description adds no syntax or format detail beyond that, so the baseline 3 is appropriate.

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

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

States a specific verb (List) and resource (roles/capabilities) scoped to the current credential, and even describes what the result conveys (catalog prefixes with read/write/admin). It is unmistakable against siblings like list_catalog or list_connectors, though it never explicitly contrasts itself with any of them.

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

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

Usage is implied — call it to discover what the current credential may do — but there is no explicit when-to-use/when-not guidance and no named alternative or prerequisite. Nothing misleading, just thin.

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

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

Annotations only flag destructiveHint=true, but the description discloses far more: which mode is destructive, that the default is non-mutating validation, and that applying 'can create, modify, or DELETE running data pipelines and their data.' It also names the backing endpoint (POST /publications) and the return shape.

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

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

Front-loaded with the safety-critical WRITE/DESTRUCTIVE warning, then the mode semantics, then the endpoint and return. Some restatement of the dry_run schema description, but every sentence is load-bearing for a destructive operation.

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

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

No output schema exists, and the description compensates by stating 'Returns the publication row.' Combined with the endpoint path and the full mutation semantics, an agent has everything needed to decide and call 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 coverage is 100%, so the baseline would be 3, but the description adds consequence-level meaning the schema does not: that dry_run=true (default) is a pure validation and that dry_run=false touches live infrastructure. detail and draft_id carry no added description value, keeping it from a 5.

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 and resource ('publish a draft') and immediately scopes it against its siblings: this is the apply step, not estuary_create_draft, estuary_list_drafts, or estuary_upsert_draft_spec. The WRITE/DESTRUCTIVE framing makes the tool's identity unmistakable at a glance.

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 strong conditional rule for using the tool: dry_run=true validates only, dry_run=false applies to the live catalog, and 'Set dry_run=false only when you intend to change live infrastructure.' It does not name an alternative tool (e.g. a separate validate endpoint), so it stops short of full when-not/alternative routing.

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

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

Annotations only supply destructiveHint=true; the description adds the genuinely useful upsert semantics (insert or replace), the composite key it upserts on, and the blast-radius constraint that only the draft is touched. It does not cover auth requirements or rate limits, but the safety profile is well communicated.

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 WRITE classification and the operation, followed by scope and endpoint detail. No filler, and each sentence carries distinct information.

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

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

With 4 required params all documented at 100% schema coverage and a destructive upsert, the description covers the remaining gaps: what is replaced, what is untouched, and the return value ('the staged row') despite there being no output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by disclosing the upsert key (draft_id, catalog_name), which tells the agent what constitutes identity for replacement rather than insertion, plus the verbatim pass-through nature of spec.

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 and resource: 'stage (insert or replace) a catalog spec inside a draft', prefixed with 'WRITE:' so the operation class is unambiguous. This clearly separates it from siblings like estuary_publish_draft and estuary_list_draft_specs.

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 context for when to use it: to modify spec content inside a draft, with the reassurance that live pipelines are unaffected until publication, which implicitly routes agents to publish_draft for going live. It stops short of naming alternatives or stating prerequisites explicitly.

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 the description reinforces this with 'Read-only RPC' — consistent, not contradictory, despite the POST transport. It adds genuine context the annotations don't: the token's provenance (a UUID on a publication, discover, or connector-tag record), the paging behavior, and the underlying control-plane endpoint. It stops short of describing response shape 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?

Front-loaded with purpose, then paging, then safety/endpoint facts — no filler or repetition. The trailing endpoint sentence is of marginal value to an agent selecting a tool, which keeps this just shy of a 5.

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

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

For a two-parameter read tool the description covers how to invoke it, but with no output schema it never says what comes back — a list of log lines, their format, or whether a continuation cursor is returned for the next page. That return-shape gap is the one thing an agent must otherwise guess.

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

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

Schema coverage is 100%, so both parameters are already documented. The description largely restates the schema (logs_token origin, timestamp paging) and only adds the minor note about the '2-arg view_logs overload'. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Fetch the log lines for a job') and scopes it to the logs_token identifier, which no sibling tool touches — every sibling is a catalog/draft/connector listing tool. An agent can distinguish this 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?

It conveys the immediate usage context (fetch by token, optionally page from a last-seen timestamp), but never says when this tool is appropriate versus simply listing records, nor any prerequisite beyond possessing the token. Usage is implied rather than stated, and there are no alternatives to route away from since no sibling returns logs.

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