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

Annotations supply only destructiveHint=false, so the description carries most of the burden and does so candidly: it discloses that the tool is untested and that the identity field is sent under a guessed key, which is the single most decision-relevant fact here. It still omits permission prerequisites, behavior when the member already exists, and error semantics, which keeps 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?

Two tight sentences with the experimental warning front-loaded ahead of the technical caveat, so an agent sees the risk first. No filler or repetition, though the telegraphic style leans on the reader knowing REST conventions.

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 with no output schema and near-empty annotations, the description covers the reliability risk but not the operational surface: required privileges, idempotency, and what a successful call returns or confirms. Adequate to attempt the call, insufficient to predict its outcome.

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 must compensate, and it does clarify the least obvious parameter by spelling out that `identity` accepts an IAM id, username, or service id and is forwarded verbatim. The `role` enum and `project_id` are left entirely to the schema, so coverage of the parameter set is partial.

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 identifies the operation only indirectly, by naming the wrapped endpoint (POST /v2/projects/{id}/members), which an agent must decode into 'add a member to a project'. It never states in plain terms that it grants a role to an identity, and it does not differentiate itself from the close siblings update_project_member, remove_project_member, or list_project_members.

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 guidance on when to call this versus update_project_member (changing a role) or list_project_members (checking existing membership). The only conditional information is the 'EXPERIMENTAL — untested' warning, which is a reliability caveat rather than usage direction.

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=false and idempotentHint=true, and the description adds real behavioral context: the effect is session-scoped state mutation, re-invocation replaces rather than accumulates targets, and credentials have no per-call analog elsewhere. It still does not say whether credentials are validated eagerly at call time or lazily on first use, nor what a successful call 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 sentences, front-loaded with the action and followed by the two constraints an agent most needs (session scope, replacement semantics). No filler or repetition, though the parenthetical '(or replace)' is partially restated by the 'Calling this again replaces the session's target' sentence.

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 and nine parameters including writeOnly secrets, the definition should say more about outcomes: whether bad credentials fail here or later, and what a caller can assume after success. The session/replacement model is well covered, but the success-failure contract is left unstated.

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 89%, so parameters like stage, verify_ssl, ca_bundle_path, prefer_zen_api_key, and region_or_url are already documented in detail in the schema. The description mentions no parameters at all, adding nothing beyond the structured fields. Baseline 3 is appropriate because the schema carries the parameter burden.

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 uses a specific verb and resource ('Establish (or replace) this session's target environment and credentials') and explicitly positions the tool against every sibling: all other tools operate against the current authenticated session. An agent can identify this as the session-bootstrap tool 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 states the prerequisite relationship clearly (other tools depend on the current session, and there is no per-call credential parameter, so this call is the setup step). It also warns that repeat calls replace the target and that v1 allows only one active target per session, which is an implicit exclusion against concurrent multi-target use. It does not spell out what to do when authentication fails or when a target must be switched mid-workflow.

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=true, so the safety profile is partly covered. The description does add real behavioral value beyond that: the operation is POST rather than DELETE, a separate DELETE endpoint exists with different semantics, and the blanket convention rule means `confirm: true` is required in practice. However, it never says what actually happens to the run (does it abort in-flight work? is it reversible? what does the response contain?), which matters for a destructive mutation.

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 text is a research memo rather than a tool description: it leads with an 'EXPERIMENTAL' caveat, then a documentation-provenance justification for the `confirm` parameter. Sentences about 02-tools.md and 03-conventions.md earn nothing for the calling agent. Nothing is front-loaded — the core action is never stated at all.

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?

This is a destructive mutation with 0% schema coverage and no output schema, so the description should explain the effect of cancelling, the consequence of the run's state, and the role of `confirm`. Instead it documents its own authoring uncertainty, leaving the agent unable to predict outcomes. The 'EXPERIMENTAL/unverified' flag is useful honesty but does not substitute for operational detail.

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

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

Schema description coverage is 0% across four parameters, so the description must carry the load and largely does not. It shows project_id as a query parameter and the id/run_id placeholders in the URL, and it flags that `confirm` is required for consistency with the cancel_* convention — the one genuinely useful parameter fact. But job_id and run_id formats are never described, and the claim that confirm is a hard requirement conflicts with the schema, where it is optional with default false.

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 never states plainly that this tool stops a running job run; the agent must infer it from the endpoint path 'POST /v2/jobs/{id}/runs/{run_id}/cancel' and the aside 'presumably deletes the run record instead of stopping it'. It spends its opening words on provenance ('EXPERIMENTAL — from an unverified example request') rather than verb+resource. It does implicitly distinguish cancel from the separate DELETE endpoint, but not from the actual siblings (get_job_run, list_job_runs, create_job_run).

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 statement of when an agent should cancel a run versus polling get_job_run or listing runs, and no prerequisites or exclusions are given. The only routing-adjacent content is a note that a DELETE .../runs/{run_id} endpoint exists and is 'not exposed as its own tool in v1', which tells the agent nothing actionable about choosing between available 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?

Annotations only declare destructiveHint=false, so the description carries most of the burden. It usefully discloses the response shape ('asset_id is present directly at the top level', no defensive extraction), which matters since there is no output schema, but it says nothing about duplicate-name handling, validation errors, or permission requirements for a create operation.

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?

It is short and front-loads the purpose, but a large share of the text is debugging trivia (the /transactional/v2/assets 404 note) that costs the agent attention without changing how the tool is called. The genuinely valuable sentence, about the response shape, is buried in parentheses.

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 5-parameter mutation tool with no output schema, the return-shape note is a meaningful addition. However, prerequisites, error behavior for invalid asset_type values, and how attributes maps to the resulting entity are absent, leaving the definition partial for its complexity.

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

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

Schema description coverage is only 40%: name and project_id have no descriptions at all, and asset_type/attributes are only partially documented. The description adds no parameter meaning beyond referencing project_id as a URL query value, 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?

The opening clause 'Generic asset creation' gives a clear verb+resource, and 'generic' hints at a default create path. It does not, however, distinguish this from sibling create tools such as upload_asset_file or explain what 'generic' excludes, so sibling differentiation is incomplete.

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: nothing says when to pick create_asset over upload_asset_file, or what prerequisites (an existing project, permissions) must hold. The only routing information given is an internal endpoint URL, which is implementation trivia rather than usage 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 only supply destructiveHint=false, so the description carries the real behavioral burden and does so well: it discloses a live credential test at creation time, the specific non-standard HTTP 460 'connection_test_failed' non-retryable failure mode, and that secrets in properties are forwarded but never echoed back. These are non-obvious traits an agent could not obtain from the schema or annotations.

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

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

The safety-critical constraint is front-loaded with an explicit IMPORTANT marker, which is the right structure for a tool that must not be called speculatively. A few phrases ('confirmed live', the parenthetical quoting the error code) are slightly redundant but still earn their place by grounding the failure mode.

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 5-parameter mutation tool with no output schema, the description covers the highest-risk unknowns (live validation, failure code, secret handling). It stops short of describing what is returned on success beyond implying no secret echo, which is the main remaining gap.

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

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

Schema coverage is 40%, so the description should compensate. It adds genuine meaning for `properties` (may carry secrets such as an access key, forwarded to the API, not returned), but says nothing about project_id, name, or description, and adds nothing on datasource_type beyond the schema's own examples.

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 never explicitly states that the tool creates a connection object in a project; it only refers to 'this call' testing credentials 'at creation time' and to 'this tool's output'. The verb 'create' plus siblings like update_connection/delete_connection let an agent infer purpose, but the description itself is framed around a behavioral warning rather than a statement of what is created.

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 an unusually explicit when-not-to-use rule: no speculative use, no placeholder credentials, only genuinely reachable external-system credentials. What's missing is routing guidance toward siblings — e.g., using list_connection_types to discover a valid datasource_type, or update_connection for existing records.

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 only destructiveHint=false, so the description must carry the behavioral load; it offers nothing about permissions, whether creation is idempotent, what happens when a job with the same name exists, or what the response contains. The phrase "confirmed live" is meta-commentary about verification status, not behavior the invoking agent can act on.

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?

It is short with no filler sentences, but the content leans on an endpoint reference and a truncated body snippet rather than front-loading the useful information. Brevity here reflects under-specification rather than tight editing.

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 7-parameter creation tool with no output schema and minimal annotations, the description is far too thin — it omits the two structural shapes of the request (simple asset_ref vs rich asset_ref_type) that the schema hints at, and says nothing about results or failure modes.

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 57%, and the description mentions only that project_id travels in the query string and the body is wrapped in {"job": {...}}. Parameters such as name, project_id itself, and description have no description text and get no help here, so the description does not 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?

The description only restates the tool as an HTTP wrapper ("Wraps POST /v2/jobs?project_id=...") rather than saying what the tool does for the caller (create a scheduled/executable job in a project). It gives no differentiation from siblings like create_job_run, create_asset, or update_job — the agent must infer everything from the name and the POST verb.

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 prerequisites, and no mention of alternatives such as create_job_run (to run it) or create_asset (to create the underlying script/notebook). The agent gets no signal about ordering 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 supply destructiveHint=false, so the description carries most of the load and does so well: it discloses non-blocking async semantics, that the return is the run's current state, and the confirmed body wrapper key {'job_run': {...}} rather than {'run': {...}}. The EXPERIMENTAL / unverified-origin warning is valuable honesty an agent cannot get from structured fields; it stops short of 5 by omitting auth or quota expectations.

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 EXPERIMENTAL caveat, then endpoint, then semantics — a sensible order, and the whole thing is only a few lines. The reference to 'spec/03-conventions.md' is not actionable for an agent and the parenthetical about the wrapper key is slightly tortuous, which keeps it at 4.

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 3-parameter create tool with no output schema, the description covers timing, return shape at a high level, and follow-up polling, which is the critical behaviour. The remaining hole is substantive: a fully undocumented 'configuration' object leaves the agent guessing at the payload, and no mention of auth or project scoping is made.

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

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

With 0% schema coverage the description must compensate, and it partially does: the URL template maps {id} to job_id and shows project_id as a query parameter. However, the 'configuration' parameter is never named — the body wrapper hint implies it but the agent must infer that configuration becomes the job_run payload, and nothing says what fields it accepts.

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 concrete verb+resource ('create job run') by naming the underlying endpoint, and distinguishes itself from the read/poll siblings by pointing to get_job_run and list_job_runs. The 'EXPERIMENTAL' framing is a caveat, not a substitute for purpose, but the purpose is still unambiguous.

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

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

Explicitly says the call returns immediately and does not block, then names the two follow-up tools to poll — that resolves the main 'what do I do next' question an agent has. It gives no when-not or prerequisite guidance (e.g., permissions, project scope), which keeps it 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?

Tool has no description.

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?

Tool has no description.

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

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

Tool has no description.

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

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

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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=true, so the safety profile is covered structurally. The description adds one genuinely useful signal — that the tool is untested and experimental — but says nothing about what is destroyed, whether dependent jobs break, or whether it is reversible.

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?

It is a single short line with no filler and the warning is front-loaded, so it is structurally clean. However, brevity here is under-specification rather than economy — the one sentence spends all its words on project status instead of tool behavior.

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, high-consequence tool with 0% schema coverage and no output schema, the description should explain impact, confirmation semantics, and failure modes. It provides none of these, leaving an agent unable to call it safely or predict consequences.

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 3 parameters, and the description supplies no meaning at all. The critical ambiguity is entirely unaddressed: 'confirm' is a boolean defaulting to false, and nothing explains whether the deletion is skipped or proceeds without it.

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

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

The description never states what the tool does; the only content is an experimental/untested warning. Only the tool name and annotation title ('Delete Connection') tell an agent this deletes a connection — the text itself is effectively a status note rather than a purpose statement.

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

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

There is no guidance on when to use this versus siblings such as update_connection or delete_project, nor any prerequisite (ownership, confirmation, irreversibility) mentioned. The 'EXPERIMENTAL — never tested' note hints at caution but gives no actionable when/when-not rule.

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=true, so the safety profile is covered. The description does add one piece of value beyond them: that success yields 204 with no response body, which matters because there is no output schema. However, it says nothing about what gets destroyed (runs, history, dependent assets) or what `confirm=false` actually does.

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?

It is a single sentence, but it is front-loaded with an internal verification note ('Confirmed live: 204') rather than the action, and the parenthetical about the generic asset-delete path is irrelevant to an agent choosing or invoking the tool. Little of the text earns its place.

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

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

This is a destructive, irreversible operation with two required parameters, an undocumented `confirm` flag defaulting to false, no output schema, and 0% schema coverage. The description addresses none of that — no scope of deletion, no confirm semantics, no error behavior — leaving an agent without what it 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 must carry all three parameters, and it effectively carries none. The path template '/v2/jobs/{id}' only weakly implies that job_id identifies the job; project_id and the boolean `confirm` (default false) are left entirely unexplained, including whether confirm must be true for deletion to proceed.

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 text never states a clean verb+resource like 'Delete a job'. It only asserts that a DELETE to /v2/jobs/{id} returned 204, from which an agent must infer the purpose. It also makes no attempt to distinguish this from siblings such as cancel_job_run, update_job, or the generic asset-delete path it mentions.

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 one usage-adjacent remark is that the generic asset-delete path 'also works' but this dedicated form is used 'for clarity' — an implementation aside, not guidance for an agent about when to call delete_job versus cancel_job_run or delete_project. No preconditions, no irreversibility warning, no confirmation guidance despite a `confirm` parameter.

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 and idempotentHint, so the bar is lower, and the description still adds real value: HTTP 204 on success, immediate effect, and cascade scope onto assets/jobs. The honest caveat that connections/members cascade is unverified is exactly the kind of context an agent needs, though permissions/auth requirements and the role of the confirm flag remain undisclosed.

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?

It is a single short sentence with no padding, but the phrasing 'Confirmed live: 204, immediate' is jargon-heavy and front-loads a status code over the operation itself. A lead clause naming the deletion would make it far more scannable.

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 an irreversible destructive tool with two undocumented parameters, no output schema, and no authentication notes, the description leaves too much out. Cascade behavior is the one well-covered area, but the confirm mechanics and failure modes an agent must handle 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 description coverage is 0% and the description says nothing about either parameter. The confirm boolean is especially critical since it presumably gates the destructive action, and the agent is given no clue whether it must be set to true for deletion to proceed.

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 never actually states the operation; the intent (irreversibly deleting a project) is inferred from the tool name and from 'cascades to the project's assets/jobs'. It focuses on behavior notes rather than a verb+resource statement, and it never names a sibling such as delete_connection or delete_job to differentiate 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?

There is no when-to-use or when-not-to-use guidance, no explicit irreversibility warning, and no routing to alternatives like update_project or delete_job. The only implied guidance is the word 'immediate', which hints at danger without instructing the agent.

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

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

The readOnlyHint annotation already tells the agent this is a safe, non-mutating read, so the bar is lower. The description does add genuine value by disclosing what the document contains (attachments, attributes, relationships), but says nothing about pagination, size, error behavior, or what happens when the asset is missing.

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?

One short, front-loaded sentence with no filler, and the parenthetical efficiently lists the payload sections. It is slightly clipped to the point of being a fragment, 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?

There is no output schema, so the description carries the burden of explaining the return shape, and it only gestures at it with three field names. Combined with two required, entirely undocumented parameters, the definition is under-specified for a tool an agent must call with correct IDs.

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 both parameters (project_id, asset_id) are required but undocumented in the schema. The description never mentions either parameter, so it does not compensate for the coverage gap at all — the agent must guess that both are plain identifiers.

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 the resource and the kind of payload ('Full asset metadata document'), but it is a bare noun phrase with no verb, so the agent must infer that this is a retrieval operation. It also never distinguishes itself from the sibling list_assets or the other asset tools, leaving the single-vs-collection distinction implicit.

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 guidance, no prerequisites, and no named alternative. The only usable signal is the implied 'get one asset' reading versus list_assets, which the agent has to derive on its own.

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?

Tool has no description.

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?

Tool has no description.

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

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

Tool has no description.

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

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

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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

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

Tool has no description.

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

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

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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 is consistent with a read. It adds real context by disclosing the wrapped endpoint and warning that the definition came from an unverified example request, which matters for trust in results. It still says nothing about what a run object contains, whether logs are included, or failure 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?

Short and front-loaded with the experimental caveat, but one of its three sentences is devoted to an endpoint not being called, which does not help the agent invoke this tool. The endpoint URL is the most useful fragment and is buried mid-sentence.

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?

All three parameters are undocumented and there is no output schema, so the description ideally would explain identifier formats and what a run result looks like. It partially compensates by exposing the REST route and flagging that the spec is unverified, but leaves meaningful gaps for a lookup tool.

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

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

Schema description coverage is 0% for three required parameters, so the description must carry the burden. It only weakly maps them to the endpoint — project_id as a query string, and an ambiguous '{id}' that presumably corresponds to job_id — leaving run_id and all ID formats 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?

The description identifies the operation via its underlying endpoint, GET /v2/jobs/{id}/runs/{run_id}, which implies retrieving a single job run. However, it never states plainly 'retrieves one job run' and offers no differentiation from siblings like list_job_runs or get_job. The heavy 'EXPERIMENTAL / unverified' hedging further reduces confidence in what the tool actually does.

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 guidance on when to call this versus list_job_runs or get_job, and no stated preconditions. The only routing remark concerns a logs endpoint that is explicitly not called, which is tangential rather than actionable.

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

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

Beyond readOnlyHint=true, the description discloses a genuinely non-obvious behavior: credentials and similarly-named secret fields are stripped from entity.storage.properties, with the rationale that SaaS configs can embed real COS/S3 credentials. That tells the agent the returned document is intentionally lossy, which annotations cannot convey. It stops short of covering error behavior or access requirements, so it is not 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?

Two sentences, front-loaded with the resource scope, followed by the redaction caveat. The dotted field path and spec-file citation are verbose but serve as verifiable evidence rather than filler, so there is little waste.

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

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

With no output schema, the description should characterize the returned document's shape; it says only 'full project document' and documents the redaction, without noting what top-level sections exist or how large the payload may be. The redaction disclosure is the most important missing piece and it is present, but overall return-value coverage is thin for a tool with 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?

The single project_id parameter has zero schema description coverage, so the description carries the full burden, yet it never mentions the parameter, its format, or whether an ID versus a name is accepted. The redaction note is about the response, not the input, so it adds no meaning to the parameter.

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 phrase 'Full project document' names the resource and implies a complete single-record retrieval rather than a list, which an agent can reasonably contrast with list_projects. However, it is a noun phrase with no explicit verb and never states that a single project is fetched by identifier, so differentiation from get_asset or get_job relies on the tool name alone.

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: nothing says to call this instead of list_projects when the full document is needed, or instead of get_asset for nested assets. No prerequisites or exclusions are mentioned, so the agent must infer selection from the name.

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 still adds substantial context: the response envelope {total_rows, results} (valuable since no output schema exists) and an honest disclosure that the query-DSL field names are inferred and may be wrong. That caveat directly prevents an agent from trusting filtered results blindly. It still omits pagination behavior and error semantics for the cursor.

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?

It is short, but the bulk of the text is hedging about inference provenance rather than describing the tool's behavior or inputs. The confirmed-envelope fact is front-loaded well, while the caveat consumes most of the remaining space.

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 five-parameter, zero-coverage, no-output-schema list/search tool, an agent needs to know what is returned, how to page with cursor, and that project_id scopes the search. The description supplies only the envelope shape and a filter caveat, leaving the calling contract substantially incomplete.

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 five parameters (limit, cursor, asset_type, project_id, name_contains) carry no documented meaning in either place. The description hints at filter field names (asset.asset_type / asset.name) that map loosely to asset_type and name_contains, but says nothing about limit, cursor, or project_id, leaving the majority of the schema unexplained.

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 never plainly states that the tool lists/searches assets within a project; it describes the HTTP endpoint it wraps (POST /v2/asset_types/asset/search). The verb+resource is only recoverable by inference from the endpoint path, and nothing distinguishes it from siblings like get_asset or create_asset.

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 or when-not-to-use guidance relative to get_asset, create_asset, or list_projects. The only usage-shaped content is a caution to re-verify filter syntax if results look wrong, which is a reliability note rather than 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?

readOnlyHint=true already covers the safety profile, and the description does add one genuine behavioral fact — that results come back in a HAL-style envelope with a 'first' href and total_count, implying cursor-based paging. However that fact is stated cryptically with no explanation of what the envelope contains or how to follow pagination, and it discloses nothing about scoping, filtering, or errors.

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?

It is short, but the opening clause "Native envelope confirmed live" is verification chatter that consumes the front-loaded position with no actionable meaning. Brevity here comes from under-specification rather than economy.

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 four-parameter, project-scoped list tool with no output schema and zero schema coverage, the description should state what is listed, how pagination is driven, and how filtering works. None of that is present, so an agent has almost nothing to call it correctly beyond guessing from parameter names.

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 four parameters (limit, cursor, project_id, name_contains), so the description carries the full burden and fails: it only obliquely hints at cursor pagination via 'first: {href}'. It says nothing about what project_id scopes to, what name_contains filters, or what limit defaults to.

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 never states that this tool lists connections. Instead it describes a response envelope shape ("{resources: [], first: {href}, total_count}") and compares pagination styles to other tools, so an agent cannot determine the verb or resource from the text alone — it would have to infer everything from the name.

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 the sibling alternatives that matter here (list_connection_types, get_connection, list_projects), and no conditions under which this tool should or should not be chosen. The only comparison drawn is about pagination shape, which does not help select the tool.

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

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

readOnlyHint=true already tells the agent this is a safe read. The only additional signal is 'GET', which duplicates the annotation rather than adding context—nothing about result size, caching, static catalog behavior, or filtering semantics 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?

The single sentence is short but that brevity reflects under-specification rather than economy; there is no front-loaded purpose statement and no structure beyond an endpoint reference.

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, no annotation beyond readOnlyHint, and an undocumented filter parameter, the description should carry the burden of explaining return shape and filtering—yet it supplies nothing. An agent cannot predict what the response contains or how to narrow it.

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 parameter name_contains has no description or type detail in the schema beyond an anyOf string/null. The description does not compensate at all—it never mentions the filter, whether it is a case-sensitive substring match, or what happens when omitted.

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 only restates the HTTP endpoint (GET /v2/datasource_types) and relies on the tool name to convey the verb and resource. It never says what a 'connection type' is or that the call returns the catalog of available datasource/connection types, so the agent must infer purpose from the name plus an internal API path.

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 guidance on when to call this versus siblings such as list_connections or create_connection, and no mention of whether the result is a prerequisite for creating a connection. Usage is left entirely 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?

The readOnlyHint annotation already establishes this is a safe read, so the description's only added value is the provenance caveat 'EXPERIMENTAL — from an unverified example request', which is genuinely useful risk context. Beyond that it says nothing about ordering, pagination behaviour, or what happens when limit/cursor are omitted.

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?

It is a single short statement with the warning front-loaded and the endpoint immediately after, so nothing is padded. The trailing ellipsis and fragment structure make it feel like a truncated note rather than a finished definition.

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, 0% parameter coverage, and no pagination explanation, the definition is too thin for a four-parameter list tool that returns a cursor-paginated collection. The experimental caveat is the only substantive information an agent gains.

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 none of the four parameters have descriptions. The description maps job_id (path) and project_id (query string) to the endpoint, but leaves limit and cursor entirely unexplained, so pagination semantics are undocumented in both the schema and the description.

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 identifies the underlying endpoint 'GET /v2/jobs/{id}/runs' which implies retrieving runs belonging to a job, but it never states the purpose in plain language and offers no differentiation from siblings such as get_job_run or create_job_run. An agent must infer the verb 'list' from the tool name alone.

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 exclusion of alternatives, and no mention of the closely related get_job_run (single run) tool that an agent could easily confuse with this one. The only implicit signal is that a job_id is required.

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 this as a safe read; the description adds non-obvious behavioral context that the pagination envelope is unstable and that resources/results/items are checked defensively, which helps an agent interpret the response. However, it says nothing about default page size, cursor semantics, filtering behavior, or error conditions.

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

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

The endpoint is stated up front, which is good front-loading, but the second sentence is long, hedged, and largely meta-commentary about spec ambiguity rather than information that changes how the agent calls the tool. It reads as an internal engineering note rather than agent-facing guidance.

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

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

With no output schema and no parameter descriptions, the definition should carry substantial weight, but it only speculates about the response envelope. An agent is left without knowledge of filtering behavior, page-size limits, or how to paginate, which are essential for a cursor-paginated list tool.

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

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

Schema description coverage is 0% across four parameters, so the description bears full responsibility for explaining them, yet it never mentions limit, cursor, or name_contains. Only project_id is obliquely referenced through the query-string fragment, leaving most inputs undocumented in both places.

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 identifies the underlying endpoint (GET /v2/jobs?project_id=...), which implies listing jobs scoped to a project, but never states the purpose in plain language. It offers no differentiation from siblings such as list_job_runs, get_job, or list_assets, so an agent must infer the boundary itself.

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 guidance on when to call this versus list_job_runs (runs of a job) or get_job (single job), nor any mention of prerequisites, pagination workflow, or how to continue via cursor. Only the required project_id scoping is implied by the URL fragment.

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's only added behavior is the 'EXPERIMENTAL — untested' warning, which is genuinely useful reliability context, but it says nothing about pagination behavior, result ordering, or membership visibility despite limit/cursor parameters.

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 with no wasted words and the experimental caveat front-loaded, but the brevity is under-specification rather than efficiency. Nothing is structured to help an agent decide or call correctly.

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 paginated list tool with no output schema and 0% schema coverage, the definition is far too thin: how to page, what fields members have, and what the response looks like are all 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 description coverage is 0% and the description adds no parameter meaning whatsoever. The role of 'limit' (default 50) and 'cursor' for pagination is completely undocumented, and even project_id's expected format is unstated.

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 only names the wrapped endpoint (GET /v2/projects/{id}/members); the verb comes from the tool name and the HTTP method is implied. It is enough to infer 'list members of a project', but it does not explicitly state the resource or scope, and gives no differentiation from siblings like list_projects or get_project.

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 at all: no mention of when to call this versus list_projects, get_project, or the add/update/remove_project_member siblings. The 'EXPERIMENTAL' note hints at caution but not at selection.

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

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

The readOnlyHint annotation already establishes this is a safe read, so the description only needs to add context. It does add the flattened result shape, which is useful, but says nothing about pagination via limit/cursor, default result counts, 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?

A single front-loaded sentence with no filler; the operation comes first and the return shape follows. It is perhaps too terse for the number of unexplained parameters, 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?

The return-field list partially substitutes for the missing output schema, which is a plus. However, with four parameters at 25% coverage and no output schema, the description leaves filtering and pagination behavior undocumented for an agent that must page results 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 only 25%, and the description compensates for none of the four parameters: type filtering, limit, cursor pagination, and name_contains are all unexplained. The word 'type' appears only as a returned field, which could be mistaken for the input filter rather than clarifying it.

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

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

States a specific verb and resource ('List projects') and even enumerates the flattened return fields, so the operation is unambiguous. It does not differentiate from siblings such as get_project or list_project_members, but the verb/resource pairing is clear.

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

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

There is no guidance on when to use this tool versus get_project (single-project lookup) or the other list_* tools. No prerequisites, no mention of pagination expectations, and no 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds genuine context beyond that: it is experimental/untested, it maps to a specific DELETE endpoint, and it carries an unverified identity-as-member_id assumption. It does not, however, explain the role of the 'confirm' flag or what happens to the member's other associations on removal.

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, with the EXPERIMENTAL warning front-loaded before the endpoint detail — exactly the right ordering for a risky tool. No filler, though the endpoint-only phrasing of the action is terse to the point of being opaque.

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 destructive tool with no output schema, 0% parameter documentation, and an unexplained 'confirm' parameter should do more work in prose. The experimental and identity-assumption warnings are good, but an agent still cannot tell from the definition whether confirm must be true to proceed or what the call returns.

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 must carry parameter meaning and largely fails to. It hints that 'identity' is being treated as member_id without verification, which is useful, but says nothing about 'project_id' or what the 'confirm' boolean gates — a significant gap for a destructive operation.

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 — removes a member from a project — and pins it to the concrete endpoint DELETE /v2/projects/{id}/members/{member_id}. It is distinguishable from add_project_member and update_project_member by the DELETE semantics, though the description never says 'removes' in prose and relies on the reader parsing the HTTP verb.

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 versus add_project_member or update_project_member, and no prerequisite/authorization conditions. The only cross-reference to a sibling (update_project_member) is about a shared data-model assumption, not about choosing between the 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?

Annotations supply only idempotentHint=true, so the description carries the behavioral burden and does so meaningfully: it discloses that the tool is untested, that the PATCH-body shape is assumed rather than confirmed, and that the payload could require a JSON-Patch array instead. That is exactly the kind of risk context an agent needs before invoking an experimental mutation, though it omits permissions, partial-update semantics for omitted fields, and error 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?

The EXPERIMENTAL warning is correctly front-loaded, and the spec reference is defensible provenance. However, the hedging ('this is an *assumption*, not a confirmed fact … could just as easily match') runs long for the amount of actionable content delivered.

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 5-parameter mutation with no output schema, no annotation coverage beyond idempotency, and zero documented parameters, the description leaves too much unspecified. It flags the experimental risk well but says nothing about which fields are updatable, what is returned, or failure modes.

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 5 parameters, so the description must compensate and largely does not: project_id, connection_id, name, description and properties are never explained. The one bit of added meaning is 'flat partial-object PATCH body', which implies omitted fields are left unchanged, but it is framed as an unverified assumption.

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 never states in plain terms what the tool does; the verb 'update' and the resource 'connection' are only inferable from the name and the incidental phrase 'PATCH body'. Most of the text is meta-commentary about provenance and uncertainty, so an agent cannot confirm the operation from the description alone.

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 tells the agent to 're-verify live' rather than when to call the tool, and it never contrasts update_connection with siblings like update_project or update_job as alternatives. The sibling names appear only as analogies for the body format, not as 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?

Given only idempotentHint=true in annotations, the description carries real weight: it discloses the RFC 6902 array body requirement (flat objects are rejected), and — most valuably — that schedule PATCHes return 200 while silently failing to persist, a failure mode an agent could not otherwise know. Minor deductions for the internal spec-file reference and the unaddressed question of whether omitting an optional field clears or preserves it.

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?

It opens with an internal status banner ('EXPERIMENTAL for schedule edits — Phase 3 (spec/02-tools.md)') rather than the tool's function, and spends sentences narrating the author's debugging history ('two separate live attempts... tried both /job/schedule and /schedule'). The actionable content is buried mid-paragraph.

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 5-parameter mutation tool with no output schema and 20% schema coverage, the definition covers the most dangerous behavior but omits basic update semantics (partial vs. full replacement, effect of null fields) and any statement of what a successful response looks like.

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 only 20% (just 'Plain cron string' on schedule), so the description should compensate more than it does; it names the three editable fields but says nothing about configuration's allowed contents or whether null means 'leave unchanged' versus 'clear'. It adds a little mapping value over the bare schema but leaves the highest-risk ambiguity unresolved.

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 never states plainly that this tool updates an existing job's name, schedule, or configuration; the purpose must be inferred from asides like 'schedule edits made through this tool' and 'name/configuration edits use the same confirmed format.' It also does no work to distinguish itself from siblings such as create_job, delete_job, or get_job.

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

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

There is a useful caution (schedule edits are unverified, prefer name/configuration edits), but no when-to-use framing, no routing to alternatives, and no prerequisites or permission notes. The agent is told the tool is risky without being told when to reach for it.

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

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

Annotations only supply idempotentHint=true, so behavioral disclosure largely rests on the description, and the phrase 'flat, partial JSON object' usefully implies unspecified fields are left untouched. However, it omits permission requirements, whether a null value clears a field, and what the response contains — meaningful gaps for a mutation tool.

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?

It is short and free of padding, but the lead sentence is spent on transport format rather than what the tool does, and the pointer to 'spec/03-conventions.md' is an external reference an agent cannot resolve at call time. 'Confirmed live' is assertion without operational value.

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

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

For a mutating tool with three parameters, no output schema, 0% schema coverage and only idempotentHint in annotations, the definition should say what gets updated, what happens on null, and what comes back. Instead it covers only body-format convention, leaving the core semantics to inference.

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 must compensate, and 'flat, partial' does convey that all fields sit at the top level and that omitted fields are not modified. It still says nothing about the null-default semantics of name and description (does passing null clear the value?) or the role of project_id as the sole required identifier.

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 never states that this tool updates a project's attributes; it opens with 'PATCH with a flat, partial JSON object', which describes wire format rather than purpose. An agent can infer 'partial update' from 'PATCH' and 'partial', but the resource and effect are only guessable from the tool name, not the text.

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 guidance, and no comparison to siblings like update_connection or update_project_member. The one sibling reference, update_job, is about body-format mechanics ('needs a JSON Patch array instead'), which is correctness info rather than a rule for choosing between 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 experimental/untested warning and the disclosure that `identity` may be a mis-assumed path segment are genuine behavioral context not present in the annotations. However, the description does not say what else changes, whether unspecified fields are preserved, what permissions are needed, or what a success response contains. It does not contradict idempotentHint=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?

The description is dominated by meta-commentary about an internal doc ('02-tools.md') and hedged speculation rather than front-loading the tool's function. The warning is worth keeping, but it should follow a one-line statement of what 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?

For a mutation tool with three required parameters, no output schema, and minimal annotations, the description omits effects, permissions, idempotency semantics, and return shape. The uncertainty caveat is useful but does not substitute for describing the operation.

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

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

Schema coverage is 0%, so the description must carry parameter meaning; it does add real information about `identity` being sent as the member_id path segment. It says nothing about `project_id`, and `role` is only explained implicitly via its enum.

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 identifies the wrapped endpoint (PATCH /v2/projects/{id}/members/{member_id}), which implies mutating a member of a project, and the required `role` enum narrows it to a role change. It never states in plain language what the tool does, so the agent must infer verb and effect from the URL.

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 guidance on when to use this rather than add_project_member, remove_project_member, or update_project. The only usage-adjacent content is a warning to 're-verify live,' which does not help an agent choose between 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?

With annotations limited to destructiveHint=false, the description carries real behavioral weight: it discloses that only one of three steps is verified, that failure can leave a data asset and a dangling attachment record behind, and that no rollback is attempted. That is unusually candid failure-mode disclosure, though it omits auth requirements, return values, and size/rate limits. Leaving orphan records is a residual side effect rather than destruction of existing data, so it does not directly contradict destructiveHint=false.

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

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

The text is dense and front-loaded with "EXPERIMENTAL", with no filler sentences. However, nearly every line is spent on confidence caveats while the core purpose goes unstated, so the space is poorly allocated for a tool-selection document.

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 six-parameter mutation tool with no output schema, the definition omits the basic operation description, the parameters beyond the two documented in schema, and any indication of what the call returns. The warning content is useful but does not substitute for the missing operational core.

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 only 33% across 6 parameters, so the description is expected to compensate — but it says nothing about name, project_id, mime_type, or description, and adds no meaning to the file_path/content_base64 choice beyond what the schema already documents. The low coverage gap is left entirely unfilled.

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 never states what the tool does in a direct verb+resource form; the agent must infer from fragments like "create-data-asset step", "attachment-creation", and "signed-URL PUT" that this uploads a file into a data asset. It does not distinguish itself from the sibling create_asset at all, so an agent cannot tell from the text whether this creates the asset, attaches a file, or both.

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 guidance on when to use this versus create_asset or any other sibling, and no note on required prerequisites such as authentication or project permissions. The only actionable advice is a caution to re-verify against a live cluster before relying on it, which is a confidence warning rather than usage routing.

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