estuary-flow

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

Adds real context beyond the annotations: it is a control-plane write via POST /drafts, it returns the created row (compensating for the absent output schema), and it clarifies that live pipelines are unaffected. It does not mention auth requirements or how the empty draft is subsequently populated, and sits in mild tension with destructiveHint=true.

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 'WRITE:' marker, then purpose, endpoint, and return value in three tight clauses. No wasted words.

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

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

For a one-parameter write tool with no output schema, the description covers what it does, where it sits in the API, and what it returns. Only minor gaps: no mention of what an empty draft requires next or any permission/rate considerations.

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 'detail' parameter, so the schema already carries the semantics. The description adds nothing about the parameter; 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+resource ('create a new empty draft workspace'), clarifies the domain concept ('staging area for catalog changes'), and distinguishes itself from siblings like publish_draft or upsert_draft_spec by scoping what a draft is.

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 'staging area for catalog changes; does not affect live pipelines' implies when to reach for a draft rather than a live operation, but it names no alternatives (e.g., publish_draft to apply changes) and states no 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 only cover readOnlyHint, so the description carries most of the behavioral burden and does it well: it discloses that the result is a single entity with both the raw `spec` and compiled `built_spec`, and even names the backing source (`live_specs_ext`). It stops short of describing not-found behavior or whether the spec is live vs draft, which is the only real 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?

Purpose is front-loaded in the first clause, followed by the return contents and then implementation detail. Three tight sentences with no wasted preamble, though the PostgREST/table identifiers are arguably implementation trivia an agent rarely 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?

With no output schema, the description usefully enumerates the returned fields (`spec`, `built_spec`) and the readOnly annotation covers the safety profile, so an agent has enough to call it correctly. Missing only edge-case behavior such as error/empty responses for a non-existent catalog_name.

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 parameter already documents the exact-match format with an example, so the baseline is 3. The description reinforces exactness via the `catalog_name=eq.<name>` and `limit=1` query fragment, but that adds little beyond what the schema already states.

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'), names the keying parameter (catalog_name), and specifies what it returns (serialized `spec` and compiled `built_spec`). This clearly separates it from the sibling `estuary_list_catalog` and `estuary_get_catalog_stats`, so an agent can route correctly without opening a 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 'by its exact catalog_name' implies you must already know the identifier, which is useful context, but there is no explicit when-to-use vs `estuary_list_catalog` (discovery) or `estuary_get_catalog_stats`, and no statement of what happens if the name is not found. Usage is implied rather than guided.

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 goes further by disclosing the returned metric set, the per-time-grain aggregation, and the optional timestamp bounding — valuable behavioral context given there is no output schema. It stops short of covering ordering or pagination behavior beyond the limit param.

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 sentences, front-loaded with what is returned before the optional filtering and provenance details. The PostgREST endpoint mention is marginally useful but is the one element that could be trimmed.

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

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

No output schema exists, but the description compensates by naming the returned fields, and annotations cover the read-only safety profile. Remaining gaps (row ordering, whether limit defaults, behavior with no matching rows) are minor for a read-only stats query.

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 grain, limit, ts_start/ts_end and catalog_name are already documented with formats and defaults. The description only restates that results are per time grain and optionally time-bounded, adding no syntax or edge-case detail beyond the schema — baseline 3 is appropriate.

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

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

States a specific verb (get) and resource (catalog stats) and enumerates the exact metrics returned — bytes/docs read/written, usage_seconds, errors, txn_count — so an agent can distinguish it from estuary_get_catalog_spec or estuary_list_catalog at a glance. Names the backing view and endpoint, reinforcing 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?

Usage is implied rather than stated: it retrieves per-grain usage stats for one entity, optionally time-bounded. There is no explicit when-to-use/when-not guidance or routing to siblings (e.g., use get_catalog_spec for configuration), so an agent must infer the boundary itself.

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. The description adds genuine context beyond that by naming the backing source ('Estuary control-plane table tenants') and the underlying PostgREST call (GET /tenants), which helps an agent reason about freshness and scope.

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

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

A single compact sentence with the resource front-loaded and return contents following. Dense but free of filler; the trailing PostgREST note is the only slightly extraneous element.

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

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

For a simple, single-parameter read with no output schema, the description compensates by enumerating the fields returned and naming the data source. It is essentially complete, with only the limit behavior left to the schema.

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

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

The single parameter (limit) has 100% schema description coverage, so the schema already documents it fully. The description contributes no syntax, default, or semantics beyond the schema, 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 ('Get the user's tenant(s)') and then enumerates what a tenant record contains (quotas, billing tiers, recurring charge, trial start, payment provider), which is far more informative than the bare title. No sibling tool touches tenants, so no differentiation is needed.

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, no prerequisites, and no named alternative. Usage is only implied by the fact that this is the sole tenant-reading tool among the 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?

Beyond the readOnlyHint annotation, the description discloses that results are scoped to entities 'the user can read' (a permission filter), that metadata includes connector and last-publication info, and names the backing source (live_specs_ext / GET /live_specs_ext). It does not describe pagination behavior despite limit/offset params, but it adds meaningful read-scope 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?

Three sentences, front-loaded with the core purpose and entity list before the filter and implementation notes. The PostgREST endpoint and view-name references are marginal utility for an agent but do not bloat the description significantly.

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 carries the return-shape burden and does so reasonably by naming the entity types and the connector/last-publication metadata. It falls slightly short on paging/return-volume expectations, but is complete enough to call correctly.

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

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

Schema description coverage is 100%, so the schema already documents limit, offset, spec_type, and name_prefix. The description restates the name-prefix and spec_type filters but adds no syntax detail (e.g., wildcard behavior is left to the schema) and omits limit/offset, so it does not meaningfully exceed the schema baseline.

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

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

The description gives a specific verb and resource ('List live catalog entities') and enumerates the entity types (captures, collections, materializations, tests), plus the payload shape (connector + last-publication metadata). It implicitly separates 'live' entities from draft-oriented siblings but never names an alternative explicitly, so it stops just short of full sibling differentiation.

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

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

It notes the filters are optional and scoped to a catalog-name prefix and spec_type, which hints at when filtering matters. However, it offers no guidance on when to use this versus estuary_list_drafts, estuary_get_catalog_spec, or estuary_list_publications, leaving the routing decision to inference.

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 safety is covered. The description adds useful context about what the call returns (connector catalog entries with titles, descriptions, logos) and the backing endpoint (PostgREST GET /connectors), but says nothing about pagination or result size relative to the 'limit' parameter.

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

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

The description is compact and front-loads the core purpose, with the endpoint reference trailing at the end. The final two fragments ('Estuary control-plane table connectors. PostgREST: GET /connectors.') are slightly telegraphic but cost 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?

For a simple read-only catalog listing with no output schema, the description covers the essential return shape but omits pagination behavior despite exposing a 'limit' parameter. It is adequate but leaves the agent to infer paging semantics.

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 in the schema. The description adds no syntax or format detail beyond mentioning the recommended filter, 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?

The description gives a specific verb and resource ('List the connector catalog — available capture/materialization Docker connectors') and even enumerates returned fields (titles, descriptions, logos). It is clear what the tool does, though it never explicitly distinguishes itself from the sibling 'estuary_list_connector_versions', which an agent could easily confuse it with.

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 hint is 'Optionally filter to recommended connectors,' which restates a parameter rather than telling the agent when to reach for this tool. There is no guidance on when to prefer it over siblings like estuary_list_connector_versions or estuary_get_catalog_stats, and no stated prerequisites.

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 safety is covered; the description adds useful context beyond that — the backing control-plane table (connector_tags), the PostgREST endpoint, and the shape of returned rows (protocol, documentation URL). It does not disclose pagination behavior despite a limit parameter.

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, front-loaded with purpose and return contents, with no wasted wording. The trailing PostgREST endpoint detail is the only part of marginal value to an 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?

For a simple, parameter-light list tool with readOnlyHint annotations and no output schema, the description covers purpose, optional filtering, data source, and partial return shape. Only pagination/limit semantics are left implicit.

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 in the schema; the description only restates connector_id as an optional filter and adds no format or semantics beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource: list connector versions, clarified as image tags, plus the extra fields returned (protocol, documentation URL). It is distinguishable from estuary_list_connectors by the 'versions' scope and by naming connector_id as coming from that sibling, though it never explicitly contrasts the two.

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?

'Optionally filter by connector_id' implies the filtering use case and points at the sibling that yields the id, but there is no explicit when-to-use/when-not guidance or named alternative for unfiltered listing.

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 useful context that this reads an Estuary control-plane table via PostgREST GET /discovers, but says nothing about result volume, pagination behavior, or default 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 terse sentences with the primary purpose front-loaded; no filler. The staccato 'Estuary control-plane table discovers' fragment is slightly clipped but adds implementation context efficiently.

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 zero-required-param read-only list tool with a fully documented single parameter and no output schema, the description covers what it returns at a conceptual level and where the data comes from. Only minor gaps around result size/pagination remain.

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

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

Schema description coverage is 100% (the single 'limit' param is documented in-schema), so the baseline is 3. The description adds no information about the limit parameter or any filtering/ordering semantics beyond what the schema already provides.

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

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

States the specific verb and resource ('List connector discovery jobs') and clarifies with a parenthetical what a discovery job does (auto-detecting bindings/resources for a capture). It is distinguishable from siblings like list_drafts or list_connectors by resource, though it does not explicitly contrast with 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 by the resource description rather than stated; there is no when-to-use, when-not-to-use, or named alternative among the many list_* siblings. An agent can infer the intent but gets no routing 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, so the safety profile is covered. The description adds that it reads the user's drafts via a PostgREST GET endpoint, but it does not cover auth requirements, pagination defaults, ordering, or rate limits, earning only partial credit 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?

Three short sentences, front-loaded with purpose. The second sentence ('Estuary control-plane table drafts') slightly restates 'draft workspaces' and the endpoint line is technical but useful, so it is effective though not maximally tight.

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 read-only list tool with full parameter schema coverage and readOnlyHint, the description covers what is listed and the scoping to user drafts. It omits pagination/ordering behavior, but no output schema exists and the operation is straightforward.

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 limit parameter is fully documented in the schema. The description does not mention limit or add any syntax, format, or default details, 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?

It states a specific verb ('List') and resource ('the user's draft workspaces'), and the parenthetical defines drafts as staging areas for catalog edits before publishing, which helps distinguish from list_draft_specs and list_catalog. However, it does not explicitly contrast with those siblings or clarify the exact difference from 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?

No explicit when-to-use or when-not-to-use guidance is provided. The parenthetical 'staging areas for catalog edits before publishing' implies a review workflow, and 'user's draft workspaces' implies scoping, but alternatives are not 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?

readOnlyHint=true already tells the agent this is a safe read. The description usefully adds that entries are staged and pending publication, plus the backing table and PostgREST endpoint, but says nothing about ordering, pagination defaults, or what an empty draft returns.

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, front-loaded fragments with no wasted prose. The trailing implementation details (table name, PostgREST route) are developer-oriented trivia that add little for an agent, keeping it just short 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-only list tool with no output schema, the description covers what is listed and its meaning, and annotations cover the safety profile. Only the return shape and pagination/ordering behavior go unmentioned.

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 (draft_id, limit) are already documented in the schema. The description adds domain framing about what draft_id scopes but no syntax or format detail beyond the schema, 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+resource ("list the staged spec entries within a draft") and clarifies what a spec entry is ("an insert/replace of a catalog entity pending publication"), which separates it from estuary_list_drafts and estuary_get_catalog_spec. It does not name the sibling tools explicitly, so differentiation requires a little inference.

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 by the scoping phrase "within a draft" and the required draft_id, but there is no explicit when-to-use/when-not-to-use or naming of alternatives such as estuary_list_drafts. An agent can infer the context but is given no routing 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, so the safety profile is covered. The description adds genuine behavioral context beyond that: the meaning of the records (publish attempts) and the job_status outcome domain (queued/success/failed), plus the underlying PostgREST endpoint. It doesn't cover pagination behavior, keeping it from 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 compact fragments with the core purpose front-loaded and no filler. Slightly telegraphic ('PostgREST: GET /publications') but each piece carries information.

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

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

No output schema exists, so the description usefully explains what records come back and what job_status values mean. Combined with a fully documented single parameter, an agent has enough to call it correctly; only return-shape/pagination detail is thin.

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 sole 'limit' parameter is fully documented in the schema as the PostgREST row cap. The description adds nothing about the parameter, so this sits at the baseline for high schema coverage.

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

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

States a specific verb+resource ('List publication history/status') and clarifies the unit of data — 'each publish attempt of a draft' — which meaningfully separates it from the action tool estuary_publish_draft and from estuary_list_drafts. It stops short of naming a sibling explicitly, so it's 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?

Usage is implied (read publication history/status rather than publish), but there is no explicit when-to-use statement, no exclusions, and no pointer to alternative tools like estuary_list_drafts or estuary_view_task_logs.

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 'Read-only RPC' statement is largely redundant. The description does add the control-plane endpoint (POST /rpc/auth_roles) and clarifies that the result covers prefixes the credential can read/write/admin, which is useful but limited behavioral context.

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

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

Two short sentences and a fragment, all front-loaded and free of waste. Every clause earns its place by stating scope, output meaning, safety class, and endpoint.

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-optional-parameter read-only control-plane RPC, the description covers what is returned and that it is read-only. It does not describe the exact result shape or pagination, but no output schema exists and the core completeness need is met.

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 optional parameter (min_capability) is fully documented in the schema with an enum and default. The description does not mention the parameter at all, so it adds nothing beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb (list), resource (roles/capabilities), and scope (current credential, catalog prefixes it can read/write/admin). The resource is clearly distinct from all siblings (catalog, connectors, drafts, etc.), so an agent can identify it 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?

The description implies when to use it (to see what the current credential can access) but gives no explicit when-to-use guidance, no exclusions, and no named alternatives among the many sibling list_* tools. Usage is inferable but not 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 only provide destructiveHint=true, so the description carries most of the burden — and it does: it discloses that dry_run=false can create, modify, or DELETE running pipelines and their data, and that the response is the publication row. It does not explain auth/permission requirements or reversibility, so not a full 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?

Every sentence earns its place: the risk profile and default are front-loaded, key tokens are emphasized, and the endpoint and return value are appended compactly with 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?

For a three-parameter mutation tool with no output schema, the description covers mode semantics, blast radius, default behavior, endpoint, and return shape — nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by spelling out the consequence of dry_run=false (live catalog mutation, possible deletion of pipelines/data) rather than just 'apply'.

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 ('publish a draft') plus the two operating modes, and the WRITE/DESTRUCTIVE framing makes it unmistakably distinct from the read/list siblings (list_drafts, list_publications) and from estuary_create_draft.

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/when-not guidance: dry_run=true (default) validates only; 'Set dry_run=false only when you intend to change live infrastructure.' This tells the agent precisely the condition that selects the risky path.

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 destructiveHint=true in annotations, the description usefully adds that the operation is an upsert/replace scoped to the draft (so the destruction is limited to an existing draft spec, not live pipelines) and that it returns the staged row. It does not cover permissions/auth or error behavior on an invalid spec, so it is not fully exhaustive.

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 marker and the core action, followed by effect scope and the upsert key. Every clause carries information; 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?

For a 4-parameter tool with full schema coverage and no output schema, the description covers purpose, side-effect scope, upsert identity, and the return value ('the staged row'), which is what an agent needs to call it correctly without inspecting further docs.

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 genuinely new semantics by naming the upsert key ('upsert on draft_id,catalog_name'), which the schema does not state anywhere. That key behavior is essential for predicting replace-vs-insert outcomes.

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') with an explicit WRITE marker, which distinguishes it immediately from read-oriented siblings like estuary_list_draft_specs and estuary_get_catalog_spec. An agent knows this mutates a draft spec, not a live 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?

Gives clear context: use it to stage edits in a draft, and live pipelines are unaffected until publishing, which implicitly routes the agent to estuary_publish_draft for the live-change step. It never names an alternative tool explicitly or states when NOT to use it (e.g. editing a live spec directly), 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?

The 'Read-only RPC' line restates the readOnlyHint annotation rather than adding to it, though the control-plane route (POST /rpc/view_logs) provides useful context that the underlying call is a POST despite being read-only. No output schema exists and the description says nothing about the shape of returned log lines, pagination limits, or retention, so meaningful behavioral gaps remain.

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 sentences, front-loaded with the core purpose and action. The trailing endpoint detail is low-value trivia for an agent calling an RPC tool, but it costs almost nothing in 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?

Parameters and safety profile are well covered, but with no output schema the description should describe the returned log lines (fields, ordering, pagination behavior), which it omits entirely. Adequate for invocation, incomplete for interpreting results.

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

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

Schema coverage is 100% and the schema descriptions already explain both the UUID source and the ISO 8601 semantics of last_logged_at. The description reinforces that the timestamp enables paging but adds no format or edge-case detail beyond the schema, so baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Fetch the log lines for a job') and immediately identifies the key input, the logs_token. This is clearly distinguishable from every sibling tool, which are all catalog/draft/tenant management operations, so an agent can select it without ambiguity.

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

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

It gives clear context for use: the token is sourced from a publication, discover, or connector-tag record, and the timestamp parameter is framed as optional paging. There are no explicit exclusions or named alternatives, but the usage context is unambiguous for a log-fetch tool.

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