Supero

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered elsewhere. The description adds only that the key is 'current' (i.e. caller-derived, not looked up by id), but says nothing about what the returned scope data looks like or whether permissions are aggregated.

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. Every word carries information and nothing is redundant.

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 is the only place return-value expectations can be set, and it says only 'scope and permissions' without indicating shape, granularity, or whether it includes role bindings. For a tool whose entire value is its return payload, that leaves a real 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?

The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. The phrase 'current API key' usefully reinforces that identity comes from the session rather than an input, which is the only semantic question this schema raises.

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 ('scope and permissions of the current API key'), which is concrete and unambiguous. It does not differentiate itself from the similar sibling rbac_get_my_access, so an agent cannot fully rule the alternative out from the text 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?

Usage is only implied by the phrase 'current API key' – it suggests no arguments are needed and that it operates on the caller's own credential. There is no explicit when-to-use, no when-not-to-use, and no pointer to rbac_get_my_access or rbac_check_permission as alternatives.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations by declaring the audit is static and never executes user code, describing the finding payload (severity, file:line or policy, evidence, exact fix pattern, fingerprint), and disclosing the gating relationship with build_go_live. No behavior contradicts the annotations.

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

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

Front-loaded with purpose and a distinct-sibling claim, then findings taxonomy, then the fix/re-run workflow — a sound ordering with no filler sentences. It is a single dense paragraph that runs long, which slightly hurts scannability, but every clause 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?

With no output schema, the description takes on the burden and delivers: it enumerates the finding shape, the severity vocabulary, and the blocking semantics. Combined with full schema coverage and read-only annotations, an agent has everything needed to call it and act on 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%, so the schema already carries per-parameter meaning, but the description adds the selection logic that the schema doesn't express — files vs. files_ref vs. project_uuid, and the project_uuid-only path auditing the latest published (or version_uuid) bundle. It doesn't add format details for files_b64gz or min_severity beyond the schema.

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

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

States a specific verb and resource ('SECURITY + CORRECTNESS AUDIT of a bundle') plus scope ('BEFORE go-live') and mode ('static; your code is never executed'). It explicitly separates itself from build_validate and build_doctor by naming what those tools miss (MONEY-01, AUTHZ-01, FLOW-01, INV-01, PUB-01, LAUNCH-01).

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 explicit routing against siblings ('finds what build_validate/build_doctor do not'), the operating sequence ('fix every blocker and critical, then re-run until clean'), and the downstream consequence ('build_go_live reports or, when enforced, refuses on outstanding blocker/critical findings'). It also states the two invocation modes: pass files/files_ref, or only project_uuid.

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 declare destructiveHint=true and openWorldHint=true, but the description goes beyond them: it explains that the bind verifies the live mapping materialized, that bound schemas use ordinary app CRUD, that unmapped tenants get refused/403, and that the downgrade gate records an attestation. It never explicitly warns what is destroyed by a rebind, which is the one annotation-relevant 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?

Front-loaded with the core action, then constraints, then the safety-critical tenant warning. The mode-by-source sentence is dense but every clause carries routing information; only minor redundancy with the schema's enum descriptions prevents 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 destructive, open-world bind operation with only two top-level params and no output schema, the description supplies the mode matrix, preconditions, tenant-binding decision procedure, and downgrade gate. 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?

With 100% schema coverage the baseline is 3, but the description adds the source-type-to-mode compatibility matrix and the requirement that `source` match a discovered stream, which are not fully captured in the schema. The tenant_binding guidance is largely duplicated from the schema, keeping it below a 5.

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

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

The opening sentence gives a specific verb and resource ('Bind source streams to the app's schemas') and the rest immediately scopes it by mode and source type. An agent can distinguish this from build_connect_data_source and build_discover_source 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 exactly which modes apply per source (postgresql/supabase/mysql all three, oracle/mongodb sync only, warehouses live only, etc.) and the precondition that discovery must have run for live modes. Explicit when-to-use and when-not-to-use guidance is present.

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 destructive annotation, the description discloses key behavioral traits: live-marked keys are auto-refused, most providers lack a test-vs-live signal, the tool reacts to the live permission result, and secret values are never echoed. These are materially important behaviors for a destructive configuration tool and are not merely restatements of the annotations.

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

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

The description is front-loaded with the core action and the most important safety constraint. It is somewhat repetitive about test/sandbox keys, but the repetition is purposeful for a high-risk secret-handling tool and does not obscure the main 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?

For a destructive, non-idempotent configuration tool with nested object parameters and no output schema, the description covers the essential context: what it configures, which keys are allowed, what happens with live keys, the permission behavior, and the fact that secrets are not echoed. An agent has enough information to invoke it safely and 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%, and the schema already documents config as test/sandbox key→value with examples, service_id as a catalog id, and project_uuid as coming from build_list_projects or build_create_project. The description reinforces the test-only constraint but does not add parameter-specific syntax or format details beyond what the schema 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?

The description states a specific verb and resource: configuring a service's keys for a project so an integration works at deploy, with concrete examples like SendGrid and Stripe TEST keys. It is clear on its own, though it does not explicitly differentiate itself from nearby sibling tools such as build_go_live or connector_test_config.

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 explicit usage boundaries: use test/sandbox keys ONLY, never send real secrets through this tool/chat, and use the admin panel for production secrets. It also explains that a deep link is returned for production secrets, so the agent knows when to stop and redirect rather than trying to configure live credentials here.

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 declare it is a non-read-only, open-world, non-idempotent write with destructiveHint=false, and the description adds context annotations cannot express: it returns a connector_id, performs no schema binding, credentials are sent to the platform and never echoed, read-only creds/Key Store are preferred, and a domain- or project-admin API key is required. It also flags the connector is a manual-trigger shell until bound.

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

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

Front-loaded with purpose and return value, then the flow, then the table_names nuance and security note — a sensible ordering with no filler sentences. Slight deduction for re-explaining table_names in both the flow and the credential paragraph, which lengthens an already dense 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?

For a 17-parameter, nested-object creation tool with no output schema, the description covers the returned identifier, the authorization prerequisite, credential safety, and how the call fits into the multi-step build sequence. Nothing an agent needs to invoke it correctly — required fields, prerequisites, follow-up tool — is left out.

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; the description goes further by explaining the operational meaning of `table_names` (omit it and let discovery + bind select tables, or pass it only when the exact sync set is known) and reinforcing credential handling. That said, much of it restates the schema's own parameter guidance rather than adding new syntax or format detail.

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 ('Create a data connector to an EXTERNAL source') and immediately scopes it to sources the app owner controls, listing the three kinds (database, REST API, warehouse). It also draws the boundary that this tool does not bind schemas, which separates it from build_bind_data_source/build_discover_source.

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

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

Gives an explicit ordered pipeline (build_connect_data_source → build_discover_source → build_bind_data_source → build_run_data_source) with the note that live reads need no run. It also states when to pass `table_names` versus omitting it, and names the failure mode ('a run before a sync bind is refused'), so the agent knows both when and when-not.

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

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

Adds real context beyond the annotations: domain-admin key requirement, plan gating, and the critical fact that the API key is returned only once (a non-idempotent, capture-immediately side effect consistent with idempotentHint=false). It does not describe failure modes or what happens on name collisions, so 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?

Three short clauses, front-loaded with the action, then constraints, then side effects, then the routing hint. 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 an irreversible-in-practice creation tool with no output schema, the description covers auth, gating, and the one-time secret return. What's missing is the response shape beyond the API key and error/conflict behavior.

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. The description clarifies that schema_namespace is minted server-side if omitted, but adds no new meaning for name/description/requirements beyond the schema text.

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 project') and the capitalized NEW plus 'Use for a fresh app' separates it from build_replace_project and build_update_project. The side effects (namespace + one-time API key) are named up front.

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?

'Use for a fresh app' gives a clear positive condition, and 'NEW' implies the boundary with replace/update siblings. It does not explicitly name an alternative tool or state when not to use it, so it stops short of a 5.

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

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

Annotations declare destructiveHint=true and non-idempotent, and the description supplies the missing why: cloud_ephemeral is a ~30-minute throwaway preview and needs platform enablement, while local hands the user a bundle. It stops short of saying what a redeploy does to an existing deployment or what is torn down, which is the key remaining unknown for a destructive 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?

Three sentences, zero filler; the action and both target options are front-loaded and the alternative-tool redirect is placed last as the exception. Every clause carries decision-relevant information.

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

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

With no output schema, an agent would benefit from knowing what a deploy returns (URL? bundle path? status handle needing build_deploy_status), which is left implicit. Otherwise the definition is complete for a 4-parameter mutation whose annotations already cover the safety profile.

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 baseline is 3, but the description adds real meaning beyond the enum strings by characterizing what each target actually produces (managed Cloud Run preview vs. handoff bundle) and stating the platform-enablement prerequisite that governs the default.

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

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

States a specific verb and resource ("Deploy a published version") and immediately disambiguates the two deployment modes by name. It also names the sibling tool (build_go_live) it is not, so an agent can route correctly without opening any 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?

Explicitly explains both targets, including the tradeoff (cloud_ephemeral is a ~30m throwaway preview requiring platform enablement) and the condition that selects the alternative tool for a permanent public URL. When-to-use and when-to-use-something-else are both covered.

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 say readOnly/openWorld=false; the description adds the operationally critical behavior: 'launching' for 5-6.5 minutes is expected due to Cloud Run IAM propagation, a ~30s polling cadence, probing the url once it appears, and a ~10 minute threshold for real failure. This is exactly the timing/semantics context annotations cannot convey.

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 action and the handoff, then the timing guidance. Nearly every sentence earns its place, though the trailing '(see the anti-loop rules)' is a dangling pointer to external content that weakens the close.

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

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

No output schema exists, and the description covers the key return signals (elapsed_s, 'launching' status, unreachable url). It stops short of describing the terminal success/failure states or the response shape beyond elapsed_s, which an agent would want before deciding to stop polling.

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

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

Schema coverage is 100%, so both parameters are already documented, including poll_url's provenance and the auto-detected default for `permanent`. The description restates the poll_url origin but never mentions the `permanent` flag or the expiry behavior it controls, so it adds little beyond the schema.

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

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

Specific verb+resource ('Poll a cloud deploy') plus explicit upstream dependencies (build_deploy or build_go_live) and the poll_url handoff. An agent can distinguish this from build_deploy/build_go_live/build_logs without opening any 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?

States exactly when to call it (after build_deploy or build_go_live, passing the returned poll_url), how often to poll (~30s), and when to stop worrying vs. when it is a genuine failure (persistent unreachable past ~10 minutes). Effectively includes when-not-to-declare-failure 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 declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, so the agent already knows this mutates external state and is not repeatable. The description adds real behavioral context the annotations don't: this triggers a job and blocks waiting on it, which is why resumption exists. It stops short of stating that a timeout leaves a job running server-side (that lives in the schema).

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, zero filler. The capability and its return payload come first, the ordering constraint second, and the critical `source`-must-match rule is parenthetical and easy to scan.

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 correctly carries the return contract, naming each artifact returned. It omits the timeout/resume behavior, but that is fully covered by the input schema, so the omission is minor rather than a hole.

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 timeout/cap/execution_id resume semantics are already fully documented in the schema. The description adds no parameter-level detail beyond the output contract, 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?

Specific verb and resource ('Discover a connector's schema') plus an enumeration of the outputs (streams, columns, primary keys, inferred schemas, mappings, namespace). An agent knows exactly what it gets back. It does not distinguish itself from the near-named siblings connector_discover / connector_discover_status, which is the one gap.

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 sequencing: run AFTER build_connect_data_source and BEFORE build_bind_data_source, with the hard constraint that a live bind's `source` must equal a discovered stream name. That gives the agent both position in the workflow and the downstream dependency that makes the call mandatory.

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 openWorldHint=false, so the safety profile is covered; the description adds real value by enumerating the concrete failure classes detected and their downstream symptoms (spinner hang, Cloud Run port-bind timeout, silently dropped reserved fields). It does not disclose the result shape (pass/fail vs. severity-tagged findings) or whether it blocks publish, which keeps it below 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?

One front-loaded sentence with the action verb first and the ordering constraint last; the failure-mode enumeration is long but each clause carries diagnostic value an agent can act on. Slightly dense as a single run-on, but 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 read-only analysis tool with full schema coverage and no output schema, the description covers purpose, ordering, and the specific defects detected. The remaining gap is what the caller gets back (findings list, severity, blocking behavior), which is the one thing an agent would still have to discover by invoking.

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 parameters are already documented, including the files/files_ref/files_b64gz alternatives and project_uuid's role in namespace checks. The description adds no parameter-level guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb (PREFLIGHT) and resource (a bundle), plus explicit temporal scope (before publish/deploy). It also names the sibling it complements and differentiates itself, so an agent can distinguish it from build_validate and build_publish without opening any schema.

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

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

Gives explicit sequencing: 'Run it after build_validate and before build_publish', and states its distinguishing condition ('catches the silent deploy-killers build_validate does NOT'). The when-to-use and the alternative are both spelled out rather than inferred.

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 annotations (destructiveHint=true, openWorldHint=true, readOnlyHint=false, idempotentHint=false), it discloses exactly what is at risk: on DEV projects only the suite's own records are created/deleted, and LIVE projects are auto-restricted to read-only suites. It also states compute cost (~2-4 min), the async run_id contract, layer-attributed findings, and the platform-enablement prerequisite.

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 front-loaded with the core action and cost caveat, and the emphasis caps are used sparingly and meaningfully. It is dense and long, but nearly every clause carries decision-relevant information rather than restating the name.

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 async, expensive, potentially destructive run with no output schema, the description supplies prerequisites, safety behavior, expected duration, the poll sibling for results, and how to triage findings. Nothing an agent needs to invoke it responsibly 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 description coverage is 100% and every parameter is documented in the schema, including the suite enum and the live_email default. The description adds contextual meaning (deployed + seeded project, published version) but no parameter-specific syntax or edge cases, so the documented baseline applies.

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

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

The description names a specific verb and resource ('Run the FULL behavioural test suite against a PUBLISHED bundle') and enumerates the covered layers (auth/RBAC, CRUD, workflows, services, aggregates, UI). It explicitly distinguishes itself from the sibling build_smoke_test ('loads + reads one row') and from a per-edit check, so an agent can select it 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?

It gives an explicit when: after build_validate + build_doctor pass, on a deployed + seeded project, as a PRE-DELIVERY gate rather than a per-edit check. It also names the lighter alternative (build_smoke_test) and the condition that selects it, plus the downstream poll tool for the async run.

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 and openWorldHint, so the description must carry the rest, and it does: it discloses the staged response behavior (status-only while running, full report when complete) and an unusual honesty constraint on the verdict. It omits polling cadence/backoff and whether calls are cheap or rate-limited, which is the remaining behavioral gap for a poll 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?

Four short clauses, front-loaded with the action and the phase split, then the report contents. Every clause carries information an agent needs (running vs. complete, verdict semantics, findings shape, failure cause) 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?

With no output schema, the description must explain return values, and it enumerates them thoroughly: verdict, per-suite pass/fail/warn/skip, findings with layer and fix hint, coverage, next_steps, and failure cause. For a one-parameter read-only poll tool, nothing material 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?

There is a single required parameter with 100% schema description coverage that already says 'The run_id from build_e2e_test.' The description adds no format, lifetime, or validity detail beyond that, so the schema does the work and 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 and resource ('Poll an e2e run') and explicitly ties it to the originating tool ('started by build_e2e_test'), which cleanly separates it from the sibling that starts runs. An agent can distinguish it from build_smoke_test, build_verify, and build_e2e_test without opening any schema.

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

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

Usage context is clear: call this to poll a run whose run_id came from build_e2e_test, and the description distinguishes the running phase from the complete phase. It stops short of explicit when-not guidance (e.g., stop polling once complete, or use build_smoke_test for a lighter check), so it is clear context rather than full routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's job is to add context — it does, by warning that skipping the bundle silently drops hand-authored ui/app.js and prior fixes, and by noting the download_url is signed. It stops short of describing freshness, caching, or how a bundle differs from a staged one.

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, zero padding, with the return modes front-loaded and the high-stakes warning placed last so it lands. Capitalized emphasis is used sparingly and only on the terms that change 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?

No output schema exists, and the description compensates by naming what comes back (file list, signed URL, or inline file content). For a read-only three-parameter fetch this is nearly complete; minor gaps are whether the signed URL expires and whether the file list is exhaustive.

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%: file, project_uuid, and version_uuid all carry descriptions including the default-to-latest behavior and the ~120KB truncation cap. The description only restates 'via file=' and 'CURRENT (or a given)', adding little beyond the schema.

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

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

States a specific verb and resource ('Fetch the CURRENT (or a given) PUBLISHED bundle') and enumerates the two return modes: file list plus signed download_url, or one file inline via file=. The 'PUBLISHED' qualifier and the version parameter implicitly separate it from build_stage_bundle and build_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?

Gives an explicit when-to-use rule ('For ANY change request on an existing app, START from this bundle') and names the alternative to avoid ('re-authoring from scratch') along with the concrete cost of that mistake. That is the when/when-not/alternative structure in two sentences.

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 and openWorldHint; the description adds materially important behavior not in the annotations — responses are paged at roughly 32KB per section, a header flag more:true signals truncation, and the agent must continue with offset=<next_offset> rather than restarting. That paging disclosure is exactly the kind of operational context that prevents a subtle failure mode.

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-loads the core action and the critical 'fetch BEFORE authoring your UI' sequencing, with paging last. Some promotional framing ('the single biggest lever for app quality', 'real stunning apps') is not strictly load-bearing, and the parenthetical about SDK components is dense, but no sentence 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?

For a read-only fetch tool with no output schema, the description compensates fully: it names every returned file, describes the index-listing response, and explains the paged response envelope (more flag, next_offset). An agent has everything needed to call it correctly and resume paging without guidance from elsewhere.

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 enum and field meanings are already covered, but the description still adds value: it explains that archetype='index' is a listing mode rather than a real app, names the valid archetype choices, and describes offset as a 'next section' pointer tied to the more flag. max_bytes is left unexplained in the prose, though the schema covers it adequately.

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

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

States a specific verb and resource ('Fetch a COMPLETE, production-quality reference app') and enumerates exactly what is returned (schemas.py + config.py + setup.py + ui/app.js). It also distinguishes itself from adjacent concepts by noting the SDK components catalog is 'optional, not what these mirror', separating it from the sdk_* and build_get_skills siblings.

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

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

Gives an explicit workflow: start with archetype='index' to list options, pick the closest archetype by name, and fetch 'BEFORE authoring your UI'. It also names the alternative path (file= for a single file) and warns against re-fetching from offset 0, which is a when-not-to-do-it instruction.

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 openWorldHint=false, so the safety profile is clear. The description adds valuable non-obvious behavior: the returned schema_namespace must be reused verbatim as the namespace literal on schema dicts, and project_intent is authoritative and must not be re-derived. Error cases (e.g., project not found) are not mentioned, but that is a minor gap against annotation coverage.

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 purpose, then the return contents, then the build directive. The long parenthetical enumerating project_intent subfields is dense but earns its place by telling the agent what to build against. There is mild redundancy between 'authoritative app spec' and 'don't re-ask or ignore it,' but no wasted sentences.

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 carries the full burden of explaining return values — and it does so thoroughly, breaking project_intent into brief, data model, and landing intent with named subfields. For a read-only single-entity fetch, this is complete enough for an agent to call and use the result 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% and the single project_uuid parameter is documented in the schema, including where to source it (build_list_projects or build_create_project). The description adds no additional meaning about the parameter itself, so the baseline of 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 (get one project's details) and enumerates exactly what comes back: schema_namespace, last published version, and the full project_intent breakdown. This contrasts implicitly with build_list_projects and build_update_project, though no sibling is named explicitly.

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

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

Gives a clear downstream directive — treat project_intent as the authoritative app spec and do not re-ask the user — which tells the agent why and how to use the result. It does not explicitly say when to call this versus build_list_projects or build_create_project, but the 'one project' framing and the schema pointer (UUID from list/create) cover most of that routing implicitly.

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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine context: it discloses that results are authoritative versus prose, that service_id='index' enumerates all services, and that the 'parts' switch controls whether contract, UI schemas, or both come back. Error behavior and response shape are not mentioned, but with no output schema and strong annotations a 4 is fair.

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 verb and resource, then the key behavioral guidance (authoritative, call before UI authoring). The 22-name parenthetical service list is somewhat heavy and reads as scope-setting rather than noise, so it earns its place, but the paragraph is dense and could be split.

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 must carry the return-value burden, and it does: it names exactly what comes back (initial_state + transitions, op ids, input fields, resulting state, base schemas, mandatory fields, default UI schemas). The remaining gap is failure modes and the shape of the index response.

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 both parameters, including the 'parts' enum values, are already documented in the schema. The description only restates the 'index' default and the deep-link purpose of the tool, adding no syntax or format details beyond structured fields. Baseline 3 under high coverage 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 ('Fetch') and a precisely scoped resource ('the AUTHORITATIVE contract for a transactional/stateful platform service'), then enumerates the returned payload: state machine, operations, base schemas, and default UI schemas. No sibling tool (schema_get, build_list_capabilities, build_get_examples) returns this combination, so the agent can differentiate without opening schemas.

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 imperative with sequencing: 'ALWAYS call this for any service your app extends BEFORE authoring its UI', plus an explicit prohibition against inferring op names, states, or mandatory fields from prose. The 'index' default is documented so the agent knows how to discover valid service IDs first. Only weakness is that no alternate tool is named, but the when/when-not guidance is unambiguous.

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 cover safety (readOnlyHint=true, openWorldHint=false), but the description adds substantial behavior: it discloses the return payload (doc + content version + SDK floor to pin) and the paging protocol (~32KB sections, more:true in the header, offset=<next_offset>, never re-fetch from 0). That is exactly the operational context an agent needs to call this repeatedly without wasting calls.

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 first sentence front-loads the purpose, and the pipe-delimited enum walkthrough is dense but scannable. It is close to the upper bound of acceptable length for one description, and a few parenthetical asides (e.g., 'what stunning means') could be trimmed without losing signal.

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, and the description compensates by naming the return fields and paging mechanics. For a doc-fetching tool with three parameters and a large enum, nothing an agent needs to invoke it correctly 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 would be 3, but the description goes further by explaining the intent of each doc value in prose rather than just listing enums. It falls short of 5 because the 'connectors' enum value present in the schema is not described, leaving one option semantically opaque.

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 ('Fetch') and resource ('Supero build reference') and enumerates the exact doc variants with what each contains. It also distinguishes itself from the sibling build_get_examples by prescribing the order in which each is read.

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 sequencing is given: read 'skills' FIRST, then 'components' plus a matching build_get_examples before authoring UI, and 'landing' is marked MANDATORY for public-facing apps. It names the alternative (build_get_examples) and the condition that selects 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?

Annos already flag destructiveHint=true and non-idempotent, and the description adds real context beyond them: required domain/project-admin key + platform cloud-deploy enablement, the permanence of the URL vs a temporary one, the return shape (public_url + poll_url), and that teardown is the removal mechanism.

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 critical distinction (PERMANENT vs ephemeral), then defaults, then return/polling chain, then teardown, then prerequisites. Dense but every sentence carries distinct, actionable 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?

No output schema exists, but the description discloses the return fields (public_url, poll_url) and the exact follow-up calls to confirm liveness and smoke-test. For a destructive 4-param deploy tool this is complete enough to invoke correctly on the first try.

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; the description still adds value by explaining that omitting version_uuid/file_id resolves to the latest published version and by framing acknowledge_findings around the audit gate (BLOCKER findings cannot be accepted). That extra gate semantics goes beyond the schema text.

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 (promote/deploy) and resource (published version → permanent public URL at <service>.supero.live) and draws the contrast with build_deploy(target='cloud_ephemeral') explicitly. An agent can distinguish this from every sibling deploy tool 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?

Explicit when-to-use vs the ephemeral sibling (~30-min throwaway), states the default resolution behavior when version_uuid/file_id are omitted, and gives the required follow-up chain (build_deploy_status → build_smoke_test). Also names build_teardown as the removal 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?

Beyond the destructive/non-idempotent annotations, the description discloses critical behavior: it uses the caller's connection credential, reports per-service outcomes, rejects false success on failed imports, and warns not to ship an app whose required service failed. It also names the failure diagnostics returned by the platform.

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 front-loaded with the action and purpose, then adds the important failure semantics and next step in a compact paragraph. Every sentence contributes operational guidance for a destructive import tool.

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 destructive tool with no output schema, the description covers purpose, credential source, failure reporting, required-service safety, and the follow-up configuration step. Nothing essential for correct invocation and post-import handling appears 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 100%, and the schema already explains both project_uuid and service_ids with examples and source tools. The description reinforces the service ID examples and prerequisite source but does not add parameter-level meaning beyond what the schema 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?

The description states a specific verb and resource: importing platform services into a project, with concrete examples such as 'workflows', 'email', and 'stripe_checkout'. It also explains the outcome so the app can call those services and run event-bound workflows, making the purpose distinct from setup/configuration siblings.

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

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

It clearly positions the tool in a workflow by saying to use build_configure_services afterward to set keys. It also implies the prerequisite that service IDs come from build_list_capabilities via the schema, but it does not give explicit when-not-to-use guidance or compare all relevant alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces this with the strong downstream warning against overwriting connector-discovered schemas, which is real behavioral context the annotations don't carry. It does not spell out the returned structure beyond the access-mode tokens, keeping it short of a 5.

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

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

Two sentences, front-loaded with the classification purpose before the rationale. The second sentence is dense but every clause carries meaning (the two destructive mistakes it prevents), so there is no padding.

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

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

For a single-parameter, read-only classification tool with no output schema, the description supplies both the dimensions being classified and the enum of access modes, which is the essential return information. A brief note on whether it lists all schemas or only bound ones would close the 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?

With only one optional parameter at 100% schema description coverage, the schema already explains that project_uuid defaults to the key's project. The description's phrase 'this project's schemas' is consistent with that default but adds no new semantics; 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 gives a specific verb ('Classify') plus the exact resource ('this project's schemas') and enumerates the two classification dimensions returned: connector-backed vs app-authored, and access mode with its four values. That is enough to distinguish it from the schema_* siblings, though no sibling is named explicitly.

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

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

It states the decision this tool enables ('Use it so you DON'T render create/edit UI for read-only live sources... or regenerate/overwrite connector-discovered schemas'), which is concrete when-to-use context. What is missing is an explicit contrast with the closest alternatives (schema_list_project, build_list_data_sources), so the agent must infer which list tool to call.

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 establish readOnlyHint=true and openWorldHint=false; the description adds that the catalog is LIVE (freshness) and that results include per-connection permissions (can_import / can_configure), which the agent could not infer from annotations. It says nothing about auth requirements or failure modes.

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?

Verb and scope are front-loaded, and each sentence carries information (examples, id-verbatim warning, descriptive-only note). The heavy parentheticals and em-dash asides make it denser than necessary.

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

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

With no output schema, the description does the work of describing return fields (service_id, category, key requirement, connection permissions), which is what an agent needs. Only minor gaps remain around call cost or result size.

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 baseline is 3. The description adds that passing service_id returns that one service's config fields, but that largely restates the schema text; the category filter is not elaborated at all.

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

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

Specific verb + resource: 'List the platform's available services/integrations from the LIVE catalog', with enumerated examples. It is clearly distinguishable from siblings like build_recommend_integrations (which advises what to use) and build_get_service_contract (which returns contract detail).

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?

States the triggering context — answering the intake's 'which connections/integrations?' question — and the exclusion 'Descriptive — what EXISTS, never what to use', which implicitly routes recommendation questions elsewhere. It never names the alternative sibling explicitly, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real value on top by enumerating the returned categories and the downstream tool chain, though it says nothing about result ordering, IDs, or shape.

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

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

Front-loaded with the verb and the content enumeration, then the workflow, then a doc pointer. Dense with em-dash lists, but every clause carries information an agent needs; nothing is padding.

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

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

With no output schema, the description compensates by enumerating what the catalog contains and where the result is consumed next. A doc pointer to build_get_skills(doc='connectors') covers deeper detail, leaving the definition sufficient for a read-only listing tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline applies.

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

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

States a specific verb ('List') and resource ('external DATA SOURCE types') and then enumerates exactly what is covered: self-hosted Postgres/MySQL/MSSQL/Oracle/MongoDB, REST APIs, warehouses, and a public-API catalog. An agent can distinguish it from build_list_bound_schemas or connector_plugins purely from this 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?

Gives a clear trigger — 'Read this to offer a connect your own data option' — and places the tool in a workflow (build_connect_data_source → build_discover_source → build_bind_data_source). It does not name a sibling to avoid or state when not to call it, so it stops short of full 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 and openWorldHint=false, so the safety profile is covered. The description adds the return field set (uuid, name, schema_namespace, live_url), which is real value given there is no output schema, but it says nothing about ordering, pagination, or what 'can build into' actually filters 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?

A single sentence that front-loads the action and scope, with the field list in a compact parenthetical. No filler, nothing to trim.

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 listing with one optional parameter and no output schema, the description covers the action and the shape of the result. Minor gap: no mention of whether results are ordered or capped beyond the limit default.

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?

Only one parameter (limit) and schema description coverage is 100%, so the schema already documents the default of 50. The description adds nothing about limit semantics, which is the correct baseline for a fully documented single-parameter schema.

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

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

States a specific verb+resource ('List projects') with a scoping qualifier ('you can build into') and enumerates the returned fields, which distinguishes it from build_list_bound_schemas and build_list_data_sources. It stops short of naming a sibling alternative, but the scope is specific enough to route an agent.

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 'you can build into' phrasing implies this is a discovery step before project-scoped operations, but there is no explicit when-to-use or when-not guidance. With many siblings (build_get_project, build_list_bound_schemas, build_list_capabilities) the description never states why to pick this list over those.

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 openWorldHint=false, so 'Read-only' is redundant. 'Rate-limited per domain' is genuinely new behavioral information beyond the annotations, but gives no magnitude, backoff guidance, or throttling error behavior, and nothing is said about auth or failure modes.

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 dense sentence: resource and scope first, then the differentiating diagnostic purpose, then the read-only/rate-limit caveat. No filler, nothing buried.

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 should hint at returns; it implies raw log text but does not describe format or ordering. For a 3-parameter read tool with annotations covering safety and a fully documented schema, this is nearly complete, with only the return shape 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% (lines default 200, since default 60, project_uuid source noted), so the schema carries the parameter burden. The description adds no meaning about the parameters — no guidance on picking line counts or time windows for a deploy failure — 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?

Specific verb+resource ('Fetch recent Cloud Run logs for a project's deployed app') with an explicit scope statement that separates it from deployment/status siblings: 'THE tool for diagnosing a failed/stalled cloud deploy or a crashing app.' Names concrete failure symptoms (startup-probe timeouts, tracebacks, PORT errors), so an agent can match a problem to this 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?

Gives a clear use context with concrete diagnostic symptoms, which is more than most definitions offer. It does not name alternatives (e.g., build_deploy_status, build_doctor) or state when not to use it, but the symptom list functions as a strong positive selector.

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 covers non-mutating behavior, and the description adds transparency by stating the tool is deterministic and returns a checklist rather than performing actions. No contradictions exist, though more detail about failure modes or empty inputs would improve transparency.

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 informative but somewhat verbose, with repetitive emphasis on planning first and the rationale behind it. It could be tightened while retaining the key sequencing and output details.

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?

Even without an output schema, the description enumerates the main return elements (build checklist, page structure, terminology, detail-page determination, multi-tenant login pattern, seed guidance, examples to copy). This gives the agent a solid expectation of what will be provided, though explicit output formatting is not described.

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

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

The schema descriptions cover all four parameters at 100%, so the tool description does not need to add much. It does add context around how entities, public_facing, and is_multi_tenant affect the returned guidance, but those nuances are already present in the input schema.

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

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

The description clearly states the tool's purpose: turning an app idea into an explicit build checklist. It names the specific outputs (page structure, terminology, detail-page guidance, multi-tenant login pattern, seed guidance, examples to copy) and distinguishes it from related build tools by specifying it should be called after build_get_skills and before authoring.

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

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

The description gives an explicit invocation sequence: 'Call it right after build_get_skills and BEFORE authoring.' It also clarifies the tool is deterministic and not LLM-based, which helps agents choose it appropriately among similar build_* 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 already declare non-read-only, non-destructive, non-idempotent. The description adds genuinely new behavior: an implicit validation stage, the precise scope of force (soft errors only, with hard failures enumerated), and the return payload. It does not say whether repeated publishes create duplicate versions or overwrite, which matters given idempotentHint=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?

Four tight sentences with the action and return value front-loaded, then behavioral caveats. The telegraphic '+' and semicolon style is efficient, though a couple of clauses (files_ref) duplicate the schema and 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?

With no output schema, the description fills the gap by naming the return fields; it also covers validation behavior, override limits, and the three ways to supply files. An agent has enough to invoke this correctly without opening 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?

Schema coverage is 100%, so every parameter including force, files_ref, files_b64gz and app_type is already documented in the schema. The description largely restates that (files format, force scope, files_ref preference), adding little semantic detail the schema lacks. 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 compound but specific action: package + upload an authored bundle and record a version under a project, plus what it returns (version_uuid, file_id, download_url). It also distinguishes itself from siblings by naming build_validate (auto-run) and build_stage_bundle (via files_ref), so an agent can place it relative to those tools.

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

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

Gives clear operating context: validation runs first automatically, force only overrides soft errors, and large bundles should use build_stage_bundle + files_ref. What's missing is explicit routing against siblings like build_deploy or a statement of when publishing is premature.

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

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

Annotations only declare readOnlyHint=true, so the description carries the real disclosure load — and it does: options are drawn ONLY from LIVE installed manifests (a hard constraint that shapes trust in results), the output is GROUPED/TIERED with a flagged default, and behavior is deterministic. It doesn't spell out what happens when no description or service_ids are supplied, which is the one remaining behavioral 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?

Front-loaded with the core action and the sibling differentiation; no filler sentences. It is dense with ALL-CAPS emphasis and stacked parentheticals, which costs a little readability, but every clause 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?

With no output schema, the description still conveys the return shape (tiers, grouping, default flag) and the provenance of the options. The notable omission is behavior when the all-optional inputs are empty, which an agent might reasonably hit given zero required parameters.

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 description's parameter notes largely restate the schema text ('region... decides the default payment gateway', 'service_ids... drives most recommendations'). The worked examples (cart/order → payment gateway, appointments → sms) add illustrative value but not new semantics per 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?

States a specific verb and resource ('RECOMMEND which concrete provider integrations this app needs') and immediately frames it as a deterministic Step-2 recommender. It explicitly contrasts itself with build_list_capabilities (prescriptive vs descriptive), so an agent can pick the right sibling without opening either schema.

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

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

Gives a direct when-to-use rule ('call this so you don't OMIT a needed integration') and names the alternative for a different need ('use build_list_capabilities for a service's exact id + config fields'). It also tells the caller which inputs to pass to get useful output.

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?

Goes well past destructiveHint=true by naming exactly what is destroyed vs retained, that a bad bundle is a validated no-op, that force never overrides hard validation failures, and that confirmation must match the project name. This is unusually rich mutation 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?

Front-loads the DESTRUCTIVE warning, then the wipe scope, then the preconditions, then the bundle behavior. Every clause carries information; nothing is padding despite the density.

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 destructive tool with no output schema, the description supplies the preconditions, side effects, failure semantics and follow-up step an agent needs. No material gap remains.

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 per-parameter meaning is already documented. The description still adds ordering semantics not in the schema: files are validated before any wipe, and force only bypasses SOFT errors. It does not re-describe files_ref/files_b64gz beyond what the schema says.

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 — completely replace a DEV-mode project's app — plus explicit scope (wipes data, retains credentials/API keys/namespace/tenant). It is unmistakable against siblings like build_update_project (partial) and build_publish (deploy-only).

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

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

Gives explicit when-not conditions ('Refused if mode="live"', DOMAIN-admin keys only) and an alternative path: pass files to publish, or wipe-only and then call build_publish. The decision tree is fully spelled out.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, and the description adds the mechanism behind that: a mode='sync' binding copies no rows until a run executes, which explains why the operation mutates state and why it is not idempotent in effect. It stops short of saying what a re-run does to already-copied rows (overwrite? append?), which matters for a destructive 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?

Leads with the action and the return value, then layers the prerequisites and exclusions. Three sentences, each doing work; slightly denser than necessary with the parenthetical re-run reminder but not padded.

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

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

There is no output schema, and the description correctly states the return (run id), along with the prerequisite tool and the binding modes that make a run unnecessary. For a destructive one-parameter trigger the remaining gap is the fate of existing target rows on repeat runs.

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 parameter already names its origin ("from build_connect_data_source"). The description references the connector only implicitly via the prerequisite build_bind_data_source step; baseline 3 is appropriate when the schema carries the parameter semantics.

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 ("Trigger a SYNC RUN on a data connector and return the run id") and scopes it to manual/mode='sync' bindings, so the agent knows exactly what effect to expect. It never mentions the sibling connector_run tool, which is the obvious near-duplicate an agent would need to disambiguate against.

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 sequencing guidance ("call this after build_bind_data_source"), a re-invocation rule ("again whenever the source data changes"), and an exclusion ("Live-read/warehouse bindings don't need runs"). When-to-use, when-to-repeat, and when-not-to-use are all present.

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, but the description adds real value by specifying what 'dev' actually permits (wipe data, keep credentials) versus what 'live' protects. It stops short of stating the return value or whether the switch itself is reversible, so slightly below top marks.

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 verb and action, then mode semantics, then the switch-timing rule. 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 2-parameter tool with full schema coverage and rich annotations, the description covers purpose, mode behavior, and switching workflow. Only the absence of any return-value note (there is no output schema) keeps it off a 5.

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

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

Schema coverage is 100% and the enum already documents 'dev'/'live' semantics in detail, so the description's mode explanation largely restates it. It adds only the 'default' fact, so the baseline 3 is correct here.

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 ('Set a project's build mode') and immediately distinguishes the two modes, naming the sibling tool build_replace_project that the 'dev' mode governs. An agent can tell it apart from build_replace_project or build_update_project without opening either schema.

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

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

Gives explicit both-direction guidance: 'Switch to dev before replacing, to live when it's in production.' The alternative (build_replace_project) is named and the condition that makes this tool a prerequisite is stated, leaving nothing 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 only declare idempotent/non-destructive, so the description must carry the behavioral load, and it does: enumerates what is HTTP-checked, explains the optional authed data-read path, and clarifies that a malformed expected_app_js_sha1 yields a warning 'never a false mismatch.' That directly informs how to interpret results beyond what the annotations state.

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-loads the verb and scope, then packs the checks and the routing hint into compact clauses. It is dense and parenthesis-heavy, but every sentence carries information; a slightly lighter structure would read more easily.

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 8-param tool with no output schema, it covers purpose, trigger, input alternates, and the semantics of the tricky sha1 check. It does not describe the shape of the pass/fail report, but the enumeration of checks generally conveys what a result means, so the gap is minor.

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 already 100%, so the baseline is 3, but the description adds genuine semantic value: it explains the url-versus-poll_url alternative and the optional login/entity-read flow that maps to email/password/entity/tenant. It stops short of restating each param, which is appropriate given the rich schema.

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

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

States a specific verb (VERIFY) and resource (a deployed app), and distinguishes the purpose from mere liveness ('not just running') and from other build tools. The parenthetical checks (root loads, app.js is your bundle, config namespace) make the scope concrete enough that an agent can tell it apart from build_validate or build_deploy_status.

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 post-deploy gate — run it after every deploy' gives an explicit trigger, and it routes the agent to build_deploy_status for the url or poll_url source. The when-to-use condition is unambiguous and the alternative input path is named.

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 declare readOnlyHint=true and openWorldHint=false, and the description is consistent: the tool only hands back an endpoint while the agent performs the upload with 'your OWN key'. It adds real context annotations cannot convey (why the endpoint exists, token-cap workaround, downstream file_id usage) but omits things like URL expiry or size limits.

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

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

Front-loads the ID label, purpose, and the size constraint in the opening clause, then the procedure and handoff. Slightly heavy in the parenthetical ('truncated/minified') and the closing 'Bundle size then no longer depends on any token cap' restates the opening rationale.

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

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

No output schema exists, and the description covers the return shape loosely ('the returned URL', 'the returned file_id'), enough to act on. A small gap remains: it's not stated whether file_id comes from this call's response or from the upload itself, nor anything about endpoint lifetime.

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?

Zero parameters, so the schema baseline is 4. The description goes beyond that by explaining how the returned artifact maps onto another tool's `files_ref` parameter, which is genuinely useful semantic glue.

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

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

States a specific verb+resource ('get the out-of-band UPLOAD endpoint for a LARGE app bundle') and immediately distinguishes it from inline bundling via `files`/`files_b64gz`. An agent can tell this apart from build_get_bundle and from passing files inline 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?

Gives the explicit trigger (bundle won't fit inline because of max OUTPUT token caps), the exact procedure (upload gzip(json {path:content}) with your own key), and the downstream handoff (pass file_id as `files_ref` to build_validate / build_publish / build_doctor). Alternatives and when-not are effectively covered by the contrast with inline files.

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 flag destructive and idempotent, but the description adds real beyond-schema context: it DELETEs managed Cloud Run services, frees their URLs, returns stopped=true when nothing is deployed, refuses non-Supero-hosted apps, and requires a domain- or project-admin API key. It also explains the consequence of stopped=false (app may still be serving and billing).

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

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

Front-loaded with the core action and scope, and every sentence carries distinct information (idempotency, refusal case, stopped-field guidance, auth). The dense em-dash chaining and caps emphasis make it slightly harder to scan than ideal.

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?

Although there is no output schema, the description explains the key return field (stopped) and how to interpret it, plus permission requirements and edge cases. Nothing an agent needs to call it correctly 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 description coverage is 100% for the single project_uuid parameter, which already documents its origin (build_list_projects or build_create_project). The description adds no further parameter semantics beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb (tear down) and resource (a project's live deployment), and explicitly scopes it to BOTH the permanent (build_go_live) app and the ephemeral preview, naming a sibling. An agent can distinguish it from build_go_live or build_deploy without opening any 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?

Explicitly states the condition for use (removing deployments), the alternative it is NOT (build_go_live), and a refusal case (projects deployed to your own AWS/GCP are refused, not silently reported stopped). It also tells the agent to re-run rather than report success when stopped=false.

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 adds the concrete list of mutable fields. However, it never explains what the 'destructive' hint means here - whether omitted fields are preserved or cleared - which is the exact behavior an agent needs before calling.

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 the verb, resource, and affected fields, and no wasted words. The field list is placed where it is most useful.

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 listed fields address the main weakness of the nested patch schema, but for a destructive mutation with a confusingly similar replace sibling and no output schema, the description should also cover patch-vs-replace semantics and what is preserved.

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%, but the 'patch' parameter is a free-form object documented only as 'Fields to update.' The description supplies the allowed keys (display_name, description, show_public, live_url), which is real added value beyond the schema rather than a restatement.

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 plus the exact metadata fields affected, so an agent knows this is a metadata patch rather than a deploy or config change. It never distinguishes itself from close siblings like build_replace_project or build_set_project_mode, which is the remaining gap.

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. With build_replace_project and build_set_project_mode in the sibling set, the description should say when a partial metadata patch beats a full replace, and no such routing information is 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 readOnlyHint=true and openWorldHint=false; the description adds meaningful context beyond that: AST-only analysis with no code execution, and the specific validation classes performed. It does not describe the result shape (issues list, error codes) or what happens on partial failure, so 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?

Dense and front-loaded: the pre-publish purpose and AST-only safety note come first, followed by the checklist. No sentence is filler.

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

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

With no output schema, the description should ideally say what a validation result contains (pass/fail, list of findings). It covers inputs and checks well, but leaves the return contract 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 the baseline is 3. The description does not add meaning about the files/files_ref/files_b64gz alternatives or project_uuid beyond what the schema already spells out.

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

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

States a specific verb (validate) and resource (locally-authored bundle) plus scope (against the live platform, pre-publish) and enumerates exactly what is checked. This is clearly distinguishable from build_publish, build_smoke_test, and schema_validate by its AST-only, pre-publish framing.

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 'BEFORE publishing' constraint gives clear timing context for when to call it. It does not name alternatives or exclusions (e.g., when to prefer build_smoke_test or build_doctor instead), so it stops short of full when/when-not 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 declare destructiveHint=true and openWorldHint=true, but the description adds substantial context beyond them: throwaway accounts are created and deleted, Stripe runs in TEST mode only (otherwise refused), no real email is sent, and the run is rate-limited at ~1-3 min. These are exactly the side-effect details that determine whether an agent should invoke a destructive, open-world 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?

Front-loaded with scope, then exclusions and timing, then the flow, which is good ordering with no filler sentences. The long semicolon-separated checklist of tested areas is dense and slightly hard to scan as a single paragraph, keeping it off 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?

There is no output schema, and the description compensates by describing the return: a score plus pass/fail/skip per check with evidence and the exact fix. Combined with timing, dry-run behavior, and the post-run consumer (build_go_live reports the latest result), an agent has everything needed to call and interpret 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 coverage is 100%, so the schema already documents all four parameters; the description reinforces the key constraint that target is always 'preview' and restates what dry_run does. It doesn't add detail for budget_s beyond the schema, so it sits just above the baseline rather than redefining parameter behavior.

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 (acceptance-test the running PREVIEW) and explicitly contrasts itself with build_audit ('reads the code' vs 'USES the deployed preview like a buyer would'). It also positions itself in the pipeline against build_deploy and build_go_live, so an agent can separate it from build_smoke_test/build_validate without opening any schema.

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

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

Gives explicit ordering ('after build_deploy, before build_go_live'), an explicit exclusion ('Only the caller's own project PREVIEW, never the live app or other projects'), and a full flow: build_audit -> build_publish -> build_deploy -> build_verify -> fix -> build_go_live. Alternatives and preconditions are named rather than inferred.

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 say readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds context by enumerating the returned facts (role values, domain, project creation ability, plan) which help an agent branch on the result. It doesn't cover failure modes (e.g., invalid or expired key), which keeps it at 4.

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 what is returned and followed by a decision cue. There's no filler and every clause adds 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's enumeration of the return payload is what makes the tool callable in practice; it does that well. It falls just short of complete because it doesn't explain error behavior when the key is invalid or unscoped.

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?

Zero parameters, baseline 4. There is nothing to disambiguate, and the description correctly implies no input is required.

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

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

It uses a specific verb ('Resolve') with a specific resource ('your API key's scope') and enumerates exactly what is returned: role, domain, project-creation capability, and plan. It's clear what the tool does, though it doesn't distinguish itself from similar siblings like apikey_get_scope or rbac_get_my_access.

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?

'Call this to decide the flow' is a useful implied usage cue ('call this first/early'), but there are no explicit exclusions or named alternatives. An agent must infer whether this differs from apikey_get_scope or rbac_get_my_access 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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is known. The description adds almost nothing beyond that — it does not say whether cancellation is graceful or immediate, what happens to partial output, or what error occurs for non-running executions. 'Running' is the only marginal added signal.

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

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

A single front-loaded sentence with zero filler. It is efficient, though so terse that the brevity shades into under-specification rather than disciplined conciseness.

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 no output schema, and the description never says what the agent gets back, whether cancellation is reversible, or how failures are surfaced. Given the destructive annotation, an agent needs more than one clause to call this confidently.

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

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

Schema description coverage is 100%, with both UUIDs documented in the schema, so the baseline is 3. The description adds no further meaning about connector_id vs execution_id or their relationship.

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

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

Specific verb+resource: 'Cancel' a 'running connector execution.' An agent can distinguish this from connector_run or connector_status without opening the schema. It stops short of naming those siblings or clarifying the boundary with connector_disable.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives. The word 'running' implies a state precondition, but whether an already-completed execution should trigger a different tool 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?

Annotations provide several crucial behavioral hints (idempotent, not destructive), which mitigates the need for the description to explain core behavioral safety. The description itself is minimally behavioral, simply stating the intent.

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 one concise sentence that perfectly summarizes the tool's function, adding no superfluous detail.

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

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

The tool requires context beyond just 'disabling' to ensure the agent selects the correct method. Since it lacks sibling differentiation, zero usage guidance, and is a destructive-adjacent action (even if non-destructive per annotations), it is 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?

With 100% schema description coverage and only one parameter, the description doesn't need to add significant value beyond naming the parameter. It relies on the schema to specify that 'connector_id' is the UUID of the connector.

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 states the basic action ('Disable a connector'), but is too general. It doesn't distinguish how it interacts with the connector resource specifically (e.g., logically disabling it, turning off services) compared to other connector management tools.

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

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

The description provides zero guidance on when or how to use this tool. There is no mention of the context where disconnection is necessary, or if any alternative tools exist.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: it does not say the operation is asynchronous, whether re-running duplicates or replaces existing discovered schemas, what the nested 'params' object can contain, or that results must be retrieved via connector_discover_results.

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

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

A single front-loaded sentence with zero filler. It is efficient, though its extreme terseness means it earns low marks on completeness rather than on structure.

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 non-idempotent, open-world mutation trigger with an untyped nested params object and no output schema, the description should explain the async lifecycle (poll connector_discover_status, read connector_discover_results) and the effect on existing schemas. None of that is present, leaving the agent to guess the call-then-poll contract.

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%: connector_id is documented as a UUID and params as optional discovery parameters. The description adds no meaning beyond the schema, so the baseline of 3 applies; the opaque nested 'params' object remains unspecified 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 gives a specific verb ('Trigger') and a specific resource ('schema/metadata discovery for a connector'), so an agent can tell it apart from connector_test or connector_run. It does not explicitly distinguish it from the closely named connector_discover_status and connector_discover_results siblings, which a single clause could have fixed.

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 connector_discover_status, connector_discover_results, or connector_test, nor any prerequisite about the connector needing to be enabled/configured first. The 'Trigger' verb hints at initiation but the required follow-up polling workflow is left entirely implicit.

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 openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that: no statement of what is returned, whether results are paginated, or whether an in-progress execution yields partial results.

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

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

A single short sentence with no wasted words, but it is under-specified rather than concise. There is nothing to front-load beyond the verb and resource.

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 must carry the burden of explaining what 'results' look like, and it does not. For a read tool that returns discovery output, the agent is left guessing about the response shape.

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

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

Schema coverage is 100%, so both UUID parameters are already well documented in the schema. The description adds no additional meaning about the relationship between connector_id and execution_id; 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 names a verb and resource ('Get discovery results'), which is better than a tautology. However, 'discovery results' is never defined, and it doesn't distinguish this tool from closely related siblings like connector_discover or connector_discover_status.

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 indication of when to call this instead of connector_discover or connector_discover_status, nor any prerequisite noted (e.g. that an execution must have run first). The agent must infer usage entirely.

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 openWorldHint=false, but the description adds almost no behavioral context. It does not explain polling behavior, terminal states, or what the execution status represents.

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 front-loaded and contains no waste. However, it is arguably too terse for a tool whose usage depends on asynchronous discovery execution semantics.

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

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

The tool is simple with only two required parameters, but there is no output schema and the description does not explain what status values are returned or how they should be interpreted. An agent must infer the polling lifecycle and result meaning.

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 fully documented in the schema. The description adds no additional meaning beyond what the schema already provides, which meets the baseline for high coverage.

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

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

The description states a specific verb and resource: get the status of a discovery execution. This is clearly distinct from starting a discovery (connector_discover) or retrieving results (connector_discover_results), though it does not explicitly differentiate itself from those siblings.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as connector_discover, connector_discover_results, or connector_status. The intended polling-after-discovery use case is implied but never stated.

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

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

Annotations already declare this is a non-read-only, idempotent, non-destructive mutation, so safety is covered. The description adds one piece of extra context — that enabling affects scheduling — but says nothing about required permissions, connector state prerequisites, or whether re-enabling an enabled connector is a no-op.

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. It is efficient, though the terseness leaves the behavioral gaps unfilled.

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 one-parameter toggle with full annotations and schema coverage, the definition is minimally adequate. It lacks the state prerequisite information an agent would need to avoid calling enable on an unconfigured connector.

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% with a single required connector_id already documented as a UUID. The description adds no format, example, or sourcing guidance 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 and resource ("Enable a connector") plus a scoping qualifier ("for scheduling"), which is enough to distinguish it from connector_disable and connector_status. It stops short of describing what enabling actually changes.

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 enable versus disable, whether the connector must be configured or tested first (connector_test, connector_test_config exist as siblings), or what preconditions cause failure. The only hint is the phrase "for scheduling."

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 openWorldHint=false, so the safety profile is covered without description help. The word 'available' hints at scoping (only usable plugins), but the description says nothing about pagination, filtering, or what 'available' excludes — a small but real gap given no output schema.

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 short sentence with the resource named up front and zero filler. Nothing is buried or redundant.

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 zero-parameter read-only list tool this is close to adequate, but with no output schema the description should hint at what each plugin entry contains (identifier, name, enabled state) so the agent knows what it can do with the result. Without that, the agent must discover the return shape empirically.

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

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

The tool takes no parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly avoids inventing filtering options that the empty schema does not support.

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 states a specific verb and resource ('List available connector plugins'), which makes the operation immediately identifiable. It does not differentiate itself from the similarly named connector_discover or connector_status siblings, leaving the agent to infer the distinction from names 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?

Usage is only implied: an agent would reasonably call this to enumerate plugins before invoking connector_enable or connector_run. There is no explicit statement of when to use this versus connector_discover or connector_status, and no prerequisites or exclusions are given.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, but the description adds nothing beyond 'manual' — no warning that triggering a sync can mutate/overwrite data, no mention of non-idempotency implications or what happens if a run is already in progress. For a destructive mutation, that is a notable 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?

A single front-loaded sentence with no waste. It is appropriately brief, though thin enough that brevity comes at the cost of completeness.

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

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

For a destructive, non-idempotent, open-world mutation with a nested free-form 'params' object and no output schema, the description says nothing about effects, return values, or the shape of params. It is under-specified for the tool's complexity.

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

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

Schema coverage is 100%, with connector_id documented as a UUID and params as an optional object, so the schema does the heavy lifting. The description adds no meaning about what execution parameters are accepted, 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?

States a specific verb ('Trigger') and resource ('connector sync execution'), and 'manual' distinguishes it from scheduled runs. It doesn't explicitly contrast with close siblings like connector_test or connector_discover, but the purpose is 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?

No guidance on when to run this versus connector_test, connector_discover, or connector_enable, and no prerequisites (configured connector, permissions) are mentioned. The agent must infer usage from the name alone.

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 openWorldHint=false, so the safety profile is covered. The description adds that the response includes recent executions, which is useful return-content context not present in any output schema, but it says nothing about how far back 'recent' reaches, whether results are paginated, or what a failed connector status looks like.

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

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

A single tight sentence with no filler, and the resource being fetched is front-loaded. It is efficient but perhaps too terse for a tool whose output the agent must interpret.

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

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

For a one-parameter read-only status tool with full schema coverage and clear annotations, the description covers the essentials: what is fetched and that execution history is included. No output schema exists, but the description names the return payload categories adequately for an agent to decide whether to call 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?

There is a single parameter with 100% schema description coverage ('UUID of the connector'), so the schema already carries the semantic load. The description adds nothing about the identifier beyond what the schema states, making the baseline 3 appropriate.

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

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

The description names a specific verb (Get) and resource (connector status and recent executions), telling an agent exactly what information comes back. It does not, however, distinguish this from closely related siblings such as connector_test, connector_discover_status, or connector_run, which an agent may reasonably 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?

There is no statement of when to call this rather than connector_test, connector_discover_status, or connector_run, nor any prerequisites or exclusions. The agent must infer usage from the tool name alone.

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 openWorldHint=true, so the safety profile and external-network nature are covered by structured data. The description adds nothing beyond that: it doesn't say whether the test is synchronous or async, how long it takes, whether it consumes quota, or what a failure looks like. There is no contradiction, but no value added either.

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 well-formed sentence with the verb and scope front-loaded; nothing is wasted. It is not padded, though it is terse to the point of omitting anything useful.

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

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

For a one-parameter read-only tool with full schema coverage, the definition is minimally adequate. Since there is no output schema, the description could have stated what a test returns (pass/fail, error detail, latency), 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 description coverage is 100% and the single parameter connector_id is documented as a UUID, so the description needn't repeat it. Baseline 3 applies since the description adds no additional meaning about the identifier (e.g. where to obtain 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 names a specific verb ('Test') and resource ('an existing connector's connectivity'), so an agent can tell it performs a connectivity check rather than a mutation. However, it does not distinguish itself from close siblings such as connector_test_config or connector_status, leaving the agent to infer the difference.

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 instead of connector_test_config, connector_status, or connector_run. The only implicit condition is 'existing', which just restates that connector_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?

Annotations say readOnlyHint=false and openWorldHint=true, meaning this 'test' is not a pure read and reaches outside the system — a non-obvious trait the description never mentions. It also omits whether the test performs real network calls, whether it can fail slowly/time out, what credentials the embedded config needs, or whether anything is persisted.

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 sentence with zero padding and the verb front-loaded — efficient, though its brevity here is closer to under-specification than to discipline.

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?

Placeholder.

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?

Top-level schema coverage is 100%, but the sole parameter is an unconstrained nested object described only as 'Connector config to test', with no documented child fields. Since the entire input is this opaque blob, the description needed to say what shape of config it accepts; it adds nothing.

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 ('Test a connector configuration'), which is clear on its own. However, it does nothing to distinguish itself from the sibling tool 'connector_test', which reads as a near-synonym — an agent cannot tell from the text which one validates config shape versus runs a live connection.

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

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

No indication of when to reach for this over 'connector_test', 'connector_enable', or 'connector_run', nor any precondition such as the connector needing to exist first. The single sentence offers no context the agent could act on.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds only that creation is scoped to the current domain and that types come from the schema. It says nothing about collision/duplicate-name behavior, validation errors, or that non-idempotent repeats may create duplicates — meaningful gaps 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?

Two tight sentences with the action front-loaded and the prerequisite second. Nothing redundant, nothing padded.

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

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

With six parameters, a nested data object and no output schema, the definition is thin: it never says what a successful create returns (an FQ name? the created object?) or how parent linkage works for nested types. The schema_list pointer partially compensates for type discovery, but an agent must still infer the response shape and error 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 tenant scoping, parent_type/parent_fq_name nesting and data key-value pairs are already fully documented in the schema. The description's pointer to schema_list for field definitions adds a little value for the nested 'data' object, but no syntax or format detail 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 ('Create a new object in the current domain'), which cleanly separates it from crud_get, crud_update, crud_delete and crud_search. The word 'object' is generic without the object_type parameter, but the second sentence clarifies that objects are schema-typed, so an agent can identify the operation.

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 routes the agent to schema_list as a prerequisite for discovering valid types and fields, which is the key gating step before calling this tool. It gives no guidance on when to prefer crud_update over re-creating, or on validation failures, so it stops short of full when/when-not coverage.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds essentially nothing beyond that — no cascade implications, no irreversibility warning, no auth/tenant scoping behavior beyond the vague 'current domain'.

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 short sentence, front-loaded with the verb and with zero filler. It is terse to the point of being under-informative, but that is a completeness issue, not verbosity.

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 multi-parameter mutation with no output schema, the description should state what happens on success, whether deletion cascades, and how the tenant parameter interacts with the session tenant. It says none of this, leaving the agent to infer behavior from annotations and schema alone.

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 uuid, tenant, and object_type are already documented in the schema, including the multi-tenant fallback and UUID addressing. The description contributes no additional parameter meaning, 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 verb 'Delete' plus resource 'an object' is identifiable, but 'object' is generic and 'current domain' is never defined in the schema or description, so the agent cannot tell what kinds of objects are deletable. It differentiates from crud_create/get/update only by verb, not by any scoping detail.

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 crud_update or schema_delete, nor any prerequisites such as required permissions or confirmation steps. The only implied usage cue is the tool name 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description contributes the useful "current domain" scoping constraint, but says nothing about behavior when the UUID does not exist, cross-domain access, or the shape of the result.

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 verb, key, and scope all appear immediately. Nothing extraneous and nothing padded.

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

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

For a simple two-parameter read there is no output schema, so the description is the only place to learn what comes back and how misses are signalled — neither is covered. Adequate to call correctly, but not complete.

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 both parameters are documented there, including examples like 'customer', 'project', 'tenant' for object_type. The description only echoes the UUID key, adding no format, case-sensitivity, or valid-type guidance beyond the schema — baseline 3.

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

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

States a specific verb ("Get") and resource ("object") with an identifying key (UUID) and a scope qualifier ("current domain"). An agent can distinguish it from crud_search (which presumably queries without a UUID), though the description never names that sibling or its own domain-bound behavior explicitly.

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

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

Usage is only implied: "by UUID" hints that this is for direct lookups when the identifier is already known, leaving crud_search as the fallback for unknown IDs. No explicit when-to-use/when-not-to-use or sibling routing is stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered structurally. The description adds that domain types vary per domain and that the domain context scopes results, which is useful. It says nothing about result shape, pagination behavior, or default limits beyond what the schema already documents.

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 core action, then the prerequisite, then the type reference. Every sentence earns its place; the type list is dense but genuinely useful lookup content.

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

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

For a read-only search with a fully documented schema, the description covers purpose, prerequisite, and valid types adequately. There is no output schema, so a brief note on return shape (list vs paged envelope, total counts) would be the only missing piece. Otherwise sufficient to invoke 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%, including sort, filter/filters distinction, limit, offset, and tenant semantics, so the schema carries the full parameter burden. The description only contributes the object_type value space. Baseline 3 applies since it adds little beyond structured fields.

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

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

Specific verb and resource: "Search/list objects of any type in the current domain," and it names the domain-scoping. It enumerates concrete system and domain object types, so an agent knows exactly what universe it operates in. It stops short of explicitly contrasting with crud_get for single-object retrieval, so sibling differentiation is only implied by the 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?

Gives an explicit prerequisite workflow: "Use schema_list first to discover available object types," which is actionable guidance an agent can follow. The type enumeration doubles as a validity reference. It does not state when to prefer crud_get or when a search is inappropriate, so exclusions are absent.

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, idempotentHint=true, and readOnlyHint=false, so safety and repeat-call behavior are covered by structured data. The description adds nothing beyond that: it never says whether this is a partial (patch) or full replace update, what happens to fields omitted from 'data', what gets destroyed, or what permission is needed 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?

A single short sentence with no filler, so nothing is wasted. But it is sized too thin for a destructive four-parameter mutation tool — the brevity reflects under-specification rather than tight, front-loaded communication.

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 no output schema and a nested 'data' payload. The description does not explain partial-vs-full update semantics, merge behavior, tenant handling, or the success/error surface — all things an agent needs before calling a write tool that annotations flag as destructive.

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 all four parameters, including the nested 'data' object and the multi-tenant 'tenant' note. The description adds no extra semantics beyond the schema, so the baseline of 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: 'Update an existing object'. The word 'existing' implicitly contrasts with crud_create and crud_delete among the siblings. However, 'object' and 'current domain' remain generic — the description never names the object types (records, schemas, etc.) or clarifies the domain scope implied by the surrounding CRUD/schema toolset.

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 guidance on when to use this instead of crud_create, crud_delete, crud_search, or the more specific schema_update. There are no prerequisites, no exclusions, and no conditions under which this generic update is the right choice over a domain-specific sibling.

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 the operation non-read-only, non-idempotent and non-destructive, but the description adds nothing beyond that: it does not say what happens if a schema is already linked, whether links are additive or replace existing ones, or what permissions are required 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?

Two very short sentences, front-loaded with the action. The second sentence largely duplicates what the schema fields already state, so it is minor redundancy rather than wasted bulk.

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, the description should cover duplicate-link behavior and the result of the call. It leaves both unspecified, so an agent cannot predict the outcome of invoking 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 100%, so the parameters are already well documented, including the 'namespace:name' resolution rule. The description's 'Accepts schema UUIDs or names' restates that both input paths exist but adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Link schemas to a project'), which is unambiguous on its own. It does not, however, distinguish itself from nearby siblings such as build_list_bound_schemas or schema_list_project, so the agent must infer which is appropriate.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternative tool is named. The second sentence describes accepted inputs rather than the conditions under which this tool should be chosen.

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 openWorldHint=false, so safety is covered. The only added context is 'current user', which implies no user identifier is needed, but the description says nothing about the return value (presumably a boolean allow/deny), error behavior for unknown permission strings, or auth requirements.

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 core action and scope appear immediately. Nothing redundant or padded.

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

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

For a one-parameter read-only tool with full schema coverage and annotations, the essentials are present. But with no output schema, the agent is left guessing whether the result is a boolean, an object, or an error for unknown permissions — one clause would have closed that 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 100% and the parameter example ('schema:manage', 'data:write') already conveys the expected format in the schema. The description adds no syntax, casing, or wildcard guidance beyond what the schema provides, 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?

States a specific verb (check) and resource (a permission) scoped to the current user, which an agent can distinguish from generic CRUD tools. However, it never distinguishes itself from the sibling rbac_get_my_access, which presumably also reports permissions, so sibling differentiation is missing.

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

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

Usage is only implied: the phrase 'a specific permission' suggests a single targeted check as opposed to a full access listing, but the description never says when to prefer this over rbac_get_my_access or apikey_get_scope. No prerequisites or exclusions are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds only the content scope (role, permissions, scope) and says nothing about return shape, whether the result is cached, or how it behaves when the caller has no role assigned.

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. Every word carries information about the resource and the returned fields.

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

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

For a no-param read-only tool this is close to sufficient, but with no output schema the description is the only place an agent could learn the return structure, and it only names three concepts without shape or nesting. It also leaves the choice between this and rbac_check_permission 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?

There are zero parameters, so the baseline is 4; nothing in the schema needs compensating for. The description correctly implies no input is required and that the subject is always the caller.

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

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

Specific verb ('get') plus resource ('current user's role, permissions, and scope'), so an agent knows exactly what it retrieves. However, it never distinguishes itself from the sibling rbac_check_permission or build_whoami, which likely cover overlapping visibility-into-identity ground.

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

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

Usage is only implied: 'current user' plus zero parameters signals a self-inspection call used when an agent needs to discover its own identity/scope. There is no explicit when-to-use, no exclusion of rbac_check_permission, and no statement of 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is known. The description's only added context is 'Use with caution,' which merely restates destructiveHint; it does not explain what data is lost, whether dependent resources cascade or block deletion, or whether deletion is permanent. No contradiction with annotations.

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

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

Two short sentences with the action front-loaded, so nothing is buried. However, the second sentence ('Use with caution') is low-value filler that consumes space without earning it.

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 mutation with no output schema, the description omits the important operational details an agent needs: what happens to dependent schemas, whether deletion is irreversible, and how failures without force_delete manifest. The schema covers parameters, but the behavioral context around a destructive operation 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 description coverage is 100%, so both schema_uuid and force_delete are already documented, including the default value for force_delete. The description adds no meaning 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 and resource ('Delete a schema from the domain'), which is unambiguous and clearly distinct from read-oriented siblings like schema_get and schema_list. It does not explicitly differentiate itself from schema_update or schema_save, but the destructive verb makes the intent 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?

'Use with caution' is a generic warning rather than guidance on when to choose this tool over schema_update or when not to delete. Nothing tells the agent how force_delete changes the decision or what preconditions (e.g., dependencies) should trigger caution, leaving usage 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the full definition, attributes and metadata come back, which is useful given there is no output schema, but it doesn't address the include_content toggle (default true) or error behavior for bad UUIDs.

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 key identifier front-loaded. The second sentence largely restates "full details" as "complete schema definition including all attributes and metadata," so there is a little redundancy but no bloat.

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 two-parameter read tool with full schema coverage and annotations, the description covers the essential return shape in the absence of an output schema. Missing only edge-case behavior such as not-found handling or the effect of include_content=false.

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 schema_uuid and include_content are already documented in the schema. The description adds no meaning beyond that and actually implies a always-complete response, which sits slightly at odds with the include_content option.

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 full details of a specific schema") and the lookup key (UUID), which is enough for an agent to distinguish it from list-style siblings like schema_list. It never names a sibling outright, so differentiation is inferred rather than stated.

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

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

Usage is only implied: fetch by UUID when you already have one. There is no explicit when-to-use versus alternatives (schema_list, schema_list_project), and no note about what to do if the UUID is unknown.

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 openWorldHint=false, so safety and scope characteristics are covered structurally. The description adds only the domain-scoping qualifier; it says nothing about result size, ordering, or whether empty domains return an empty list.

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

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

A single front-loaded sentence with no filler. It is efficient, though the word "existing" is slightly redundant and the domain scoping could be made more explicit.

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 zero-arg list tool with no output schema, the description is adequate but thin: it never indicates what a returned schema entry contains or how to go from a listed schema to a fetch (schema_get). Against a crowded schema_* sibling family, that leaves a real 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter claims are made that could mislead.

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 all existing schemas") plus a scope qualifier ("in the current domain"). It does not distinguish itself from the sibling schema_list_project, so an agent cannot tell from the text alone which listing tool to pick.

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