NEXUS AI

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

Annotations already declare this is a non-readonly but non-destructive mutation. The description adds real behavioral value beyond them: it discloses the side effect of injecting S3_* environment variables and the consequential requirement to redeploy. It stops short of covering auth/permission needs or reversibility (which detach implies).

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, front-loaded with the core action and mechanism, then the redeploy constraint. Every clause carries information; nothing 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?

For a two-parameter mutation with safety annotations and no output schema, the description covers the mechanism and the key downstream consequence. It is largely complete, missing only param details and edge cases like deployment state prerequisites.

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

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

Schema description coverage is 0% and the description provides no meaning for bucketId or deploymentId beyond their self-evident names. With two undocumented required parameters, the description fails to compensate for the coverage gap.

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

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

States a specific verb and resource — 'Expose the bucket to a deployment' — and goes beyond the name by naming the concrete mechanism (S3_* env var injection). It is clearly distinguishable from sibling attach/detach tools by resource pairing, though it does not explicitly name the inverse (nexusai_bucket_detach).

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

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

Usage is implied by the action ('expose bucket to a deployment') and it notes 'Requires redeploy', which is a useful prerequisite. However, it never states when to prefer this over nexusai_bucket_detach, nexusai_volume_attach, or nexusai_managed_db_attach, nor any exclusion conditions.

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, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds useful context that the bucket is org-scoped and lives on a shared MinIO instance, but says nothing about naming collisions, idempotency, or required permissions on 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?

A single front-loaded sentence with zero filler. It is efficient, though arguably too terse for a mutation tool given what it leaves unsaid.

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 3-parameter create tool with annotations covering the safety profile and no output schema, the description is minimally sufficient. It nonetheless omits behavior on duplicate bucket names and any prerequisite/permission notes that would matter before invoking a write.

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 67%: 'name' documents the slug format and 'region' documents the default, while 'displayName' is undocumented. The description adds no parameter-level meaning, so it neither compensates for the gap nor does harm; the schema carries most of the burden.

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

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

The description states a specific verb (Create), resource (bucket), and scope (org-scoped on a shared MinIO instance). It is clearly distinct from siblings like nexusai_bucket_list, nexusai_bucket_delete, and nexusai_volume_create, though it does not explicitly name an alternative.

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

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

There is no when-to-use or when-not-to-use guidance and no reference to alternatives such as nexusai_bucket_attach for wiring an existing bucket. The agent must infer usage purely from the verb and resource.

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 destructiveHint=true, but the description adds crucial context: 'ALL objects in the bucket are deleted' and the precondition of detachment. This goes beyond annotations by detailing scope of destruction and dependency requirement, which is essential for a destructive 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?

Three short sentences, front-loaded with the primary action, then critical preconditions and consequences. Every sentence earns its place with no waste.

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

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

Given the tool's destructive nature, no output schema, and simple parameter, the description covers all necessary context: what it does, when it can be called (after detachment), and the full impact (all objects deleted). 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 0% schema description coverage and a single required parameter (bucketId), the description doesn't elaborate on the parameter's format or source. However, for a simple ID parameter on a delete tool, the lack of additional semantics is acceptable; the baseline for 0 params is 4, but here it's 1 param, so the score is slightly lower as no extra meaning is added.

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 (delete) and resource (bucket), clearly distinct from siblings like nexusai_bucket_detach, nexusai_bucket_file_delete, or nexusai_volume_delete. An agent can immediately tell what this tool does.

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

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

Provides a critical precondition: 'Must be detached from all deployments first.' This implies the detach tool (nexusai_bucket_detach) is a prerequisite, giving clear guidance on when not to call directly. However, it doesn't explicitly name the detach sibling or mention other uses.

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 and destructiveHint=false, so the safety profile is partly covered. The description contributes real value beyond that by explaining the consequence (S3 env vars stop being injected) and, importantly, that the effect is deferred to the next deploy rather than immediate — a timing detail the 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?

Two short sentences, zero filler, with the core action front-loaded and the consequence immediately after. Nothing could be cut without losing 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?

For a two-parameter mutation with no output schema, the description covers what changes and when it changes, which is the essential behavioral context. It does not mention permissions, reversibility, or whether the detach is confirmed asynchronously, which would have made it fully 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 description coverage is 0% and the description says nothing about bucketId or deploymentId, so it does not compensate for the missing schema docs. However, both parameters are self-describing identifiers of the two entities the description already names, so the gap is minor rather than severe.

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 ('Remove the bucket from a deployment'), which reads as the inverse of the sibling nexusai_bucket_attach and is clearly distinct from nexusai_bucket_delete since the bucket itself survives. The second sentence sharpens the scope by naming the concrete effect. It never explicitly names the sibling it is not, which keeps it just short of a 5.

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 can infer you detach when you want to stop a deployment consuming a bucket, and the 'next deploy' note hints at when the change takes effect. There is no explicit when-to-use, no exclusion such as 'use bucket_delete to remove the bucket entirely', and no 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, readOnlyHint=false, and openWorldHint=false, so the safety profile is known. The description adds nothing beyond that: no mention of irreversibility, permission/credential requirements, or whether the deletion can be undone. With annotations carrying the burden this is not fatal, but the description contributes no additional behavioral context.

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

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

A single sentence with zero filler and the key scope ('single file') front-loaded. It is efficiently structured, though the terseness borders on under-specification rather than true economy.

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

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

For a destructive mutation with 0% parameter documentation, no output schema, and no annotations covering permissions or reversibility, the description is too thin. An agent knows what it does but not how to target the file safely or what constraints apply.

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

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

Schema description coverage is 0%, so both bucketId and key are undocumented anywhere. The phrase 'file from a bucket' only loosely implies the two parameters and gives no format detail (is bucketId an ID or name? is key a full path, prefix, or filename?). The description fails to compensate for the coverage gap.

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

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

The description gives a specific verb and resource ('Delete a single file from a bucket'), which cleanly separates it from bucket-level siblings like nexusai_bucket_delete and file-transfer siblings like nexusai_bucket_file_upload/download. It stops short of explicitly naming those alternatives, but the scope ('single file') 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?

There is no guidance on when to use this tool versus nexusai_bucket_delete (whole bucket) or the upload/download siblings, and no stated preconditions. The description offers only the bare action, leaving the agent to infer context from the name.

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

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

Annotations already declare this a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description nonetheless adds meaningful context: the URL is short-lived, requires no API token, and the URL itself acts as a bearer credential, which carries real security implications for handling the output.

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, front-loaded with the core action and ending with a security caution. Every clause earns its place with no redundancy.

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 three-parameter URL-issuing tool with safety already covered by annotations and no output schema to explain, this is largely complete. Minor gaps remain around default TTL visibility and whether the returned URL needs further handling, but nothing blocks correct invocation.

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 covers 2 of 3 parameters (key, ttlSeconds) at 67%, with bucketId left undocumented. The description adds no explicit parameter guidance, though 'short-lived' loosely hints at the TTL parameter and 'file from a bucket' maps to key/bucketId. Adequate but not compensating for the coverage gap.

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

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

Specific verb (Issue), specific resource (short-lived signed URL), and specific target (file from a bucket). It clearly distinguishes itself from sibling bucket tools like file_upload, file_delete, and files_list by describing a URL-issuing read path rather than a mutation or listing 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?

The phrase 'without an API token' implies the use case (shareable, credential-free access) and 'share with caution' adds a caution, but there is no explicit when-to-use, when-not, or named alternative. No sibling is referenced, leaving the agent to infer context 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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds nothing beyond that: no ordering guarantee, no pagination/continuation behavior, and no note on what happens when a bucket is empty or the prefix matches nothing.

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 filter option is attached where it belongs. Nothing extraneous.

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

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

A read-only listing tool with no output schema needs to tell the agent how the results are shaped and how to page past the 1000-key limit; neither is addressed. The description is minimally viable given the annotations, but leaves pagination and result format unspecified.

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

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

Schema coverage is 67%, with bucketId undocumented. The description reiterates the prefix filter (already described in the schema) but says nothing about limit, the default of 1000, or the maximum cap, so it only marginally compensates for the coverage gap.

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

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

States a specific verb and resource ('List objects in a bucket') with a scope qualifier (prefix filter). It is distinguishable from nexusai_bucket_list (buckets) and nexusai_bucket_file_download, though it never explicitly names the sibling it is not.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives among the many sibling tools. The only usage signal is the implied 'use prefix to narrow results,' which an agent could infer from the schema parameter anyway.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=false, so the write profile is covered. The description adds real behavioral value by disclosing the ~10MB size ceiling and why base64-over-JSON is unsuited to large files, though it never says whether an upload overwrites an existing object at the same key — the key destructive detail given destructiveHint=true.

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

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

Two sentences, purpose front-loaded, with the constraint and the alternatives packed into the second without wasted words. No repetition of schema or annotation 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 write tool with annotations covering safety and no output schema, the description covers the key operational constraint and escape hatches. The remaining gap is overwrite/conflict semantics on an existing key, which an agent would want before calling a destructive upload.

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 75%, with key, contentType and contentBase64 documented in-schema and only bucketId bare. The description reinforces the meaning of contentBase64 (base64-over-JSON) but adds no syntax, encoding, or size-per-call detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ("Upload a file to a bucket") plus the transfer mechanism ("from base64-encoded content"), which cleanly separates it from file_download, file_delete, and files_list among the bucket 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 when-not boundary (~10MB decoded) and names two concrete alternatives — the CLI (`nexus bucket upload`) and the streaming PUT endpoint — so the agent knows exactly when to route elsewhere. Nothing is left 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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the org-scoped constraint, which is useful behavioral context, but it does not disclose pagination, return format, or permission 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 waste. The parenthetical adds clarifying detail without 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 trivial, parameterless list tool with rich safety annotations, the description is nearly complete. It could be improved by hinting at the return shape or pagination behavior, but no output schema exists and the core calling information is present.

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

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

The tool takes zero parameters, so there is no parameter semantics for the description to clarify. Per the baseline for parameterless tools, a score of 4 is appropriate.

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

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

The description states a specific verb (List) and resource (org-scoped object-storage buckets), and the parenthetical clarifies the technology (S3-compatible MinIO). It implicitly distinguishes from siblings like bucket_create, bucket_delete, and bucket_files_list by focusing on listing buckets at the org level.

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

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

The description gives no when-to-use guidance, no prerequisites, and no explicit alternatives. It merely states what the tool does, leaving the agent to infer when to call it versus other bucket or list operations.

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 readOnlyHint=false, so the mutation risk is covered. The description adds real value beyond that: it explains that previous credentials are replaced (invalidated) and that attached deployments must be redeployed to pick up new S3_* env vars — an operational consequence the 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?

Three tight sentences: what it does first, then when to use it, then a critical operational caveat. Every sentence carries distinct information with no filler.

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

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

For a destructive mutation with no output schema, the description covers the action, the two motivating scenarios, and the follow-up redeploy requirement. It could note whether the newly generated credentials are returned to the caller, but that is a small omission against otherwise strong coverage.

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

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

Schema coverage is 0% for the single bucketId parameter, and the description only implies its meaning via 'per-bucket.' The parameter is self-evident from name and context, so the description neither compensates nor misleads, landing at the minimum-viable baseline.

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

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

States a specific verb and resource: 'Generate fresh per-bucket MinIO service-account credentials, replacing the previous ones.' This clearly separates it from siblings like nexusai_bucket_create (creates a bucket) or nexusai_bucket_attach (attaches an existing one), so an agent can disambiguate 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 two concrete when-to-use triggers: migrating legacy buckets off shared root creds and responding to a credential leak. It does not name an alternative tool to prefer in any scenario, but no obvious sibling overlaps this rotation behavior, so the gap is minor.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description does add useful context that this returns the latest snapshot including builder-UI edits, but it says nothing about the return shape (file paths, contents, binary handling) despite there being 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?

One tight sentence with the resource and scope front-loaded and no filler. It earns its length, though the purpose clause could have been split for a clearer routing 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?

For a simple read-only pull with one required parameter and no output schema, the description covers the essential intent and freshness semantics. It is adequate but leaves an agent guessing about what 'file set' actually contains and how edits in the builder UI surface.

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

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

Schema description coverage is 100% and there is a single, fully documented projectId parameter, so the schema carries the burden. The description adds no syntax, format, or sourcing detail beyond what the schema already states; 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 (Read) and resource (the current file set of the project's AI Builder session), which clearly distinguishes it from the write-oriented sibling nexusai_builder_push. However, it never names that sibling explicitly, so the 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?

The trailing clause 'so you can continue iterating in chat' implies the usage context (fetching state before further work), but there is no explicit when-to-use guidance and no mention of when not to use it versus nexusai_builder_push or the bucket file 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 mark this as a non-destructive, non-open-world mutation, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the call returns a builder URL, the app runs in a live preview, and each push is a restorable checkpoint. It does not say whether a push replaces or merges with files already in the session, which is the main remaining risk for a mutating 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, front-loaded with the action, then the outcome, then the checkpoint property. No filler, no restatement of the name, and each sentence contributes a distinct fact.

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 covers the return value (a builder URL) and the mutating semantics via the checkpoint note. For a 3-parameter tool this is nearly complete; the gap is not stating whether pushing over an existing session overwrites or merges prior files.

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 schema already documents 'complete file set, not diffs', the relative path example, the optional transcript note, and where projectId comes from, leaving the description nothing extra to contribute about individual parameters.

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

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

The description states a specific verb and resource: pushing an app file set into the project's AI Builder session. It's clearly distinguishable from most siblings (deploy_*, bucket_*), but it never acknowledges nexusai_builder_pull, the obvious counterpart that performs the inverse operation. An agent can infer push vs. pull from the names, not from the text.

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

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

There is no explicit when-to-use guidance, no mention of prerequisites (an existing builder session, a valid projectId from nexusai_projects_list), and no contrast with nexusai_builder_pull or the deploy_* tools. The workflow sentence ('see the app running in a live preview, iterate, and deploy') hints at intent but never states when this tool is the right choice over its siblings.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description adds context beyond that: the change is DDL (schema-mutating, not data-only), and there is a mandatory human-approval gate before invocation. It stops short of stating irreversibility or rollback behavior.

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

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

Two sentences, zero filler, front-loaded with the action and its origin tool. The approval requirement follows immediately as a hard precondition.

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, no-output-schema mutation tool whose annotations already cover the safety flags, the description supplies the essential workflow context (provenance plus approval gate). It omits failure behavior and reversibility, which are the only notable remaining gaps.

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

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

Schema coverage is 100% and both parameters carry clear descriptions, so the baseline is 3. The description adds provenance the schema lacks: proposalId is specifically the identifier of a proposal previously emitted by nexusai_db_propose_fix, which tells the agent where the value must come from rather than just its type.

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 ('Apply a DDL fix') and explicitly ties the tool to the sibling that produces its input, 'nexusai_db_propose_fix'. An agent can distinguish this from nexusai_db_propose_fix and the other db_* siblings 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 the explicit precondition for calling: the proposal must come from nexusai_db_propose_fix, and the human must be shown the proposal and give explicit approval first. This is a genuine when-to-use gate that routes the agent through the correct workflow rather than leaving sequencing 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=false, destructiveHint=false, and openWorldHint=false, so the agent knows this is a non-destructive creation. The description only adds the 'in a Docker deployment' scoping context; it says nothing about whether the backup is synchronous, where the artifact is stored, or how it is later retrieved (via nexusai_db_backup_list / _download).

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 it is arguably too terse given the number of adjacent backup/restore tools it must be distinguished from.

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 creation/mutation tool with no output schema, the description should ideally say what is produced and how to consume it. It omits the natural follow-up (listing or downloading the backup) and any timing or retention note, leaving a meaningful gap for an agent orchestrating a backup workflow.

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 even carries a routing hint to nexusai_db_services_list. The description adds no parameter detail beyond the schema, which is the correct baseline when the schema fully documents its inputs.

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

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

The description gives a specific verb and resource: 'Create a backup of a database service.' It is clear what the tool does, but it does not distinguish itself from near-siblings like nexusai_db_backup_schedule (scheduled vs. one-off) or nexusai_managed_db_snapshot_create, leaving the agent to infer which backup mechanism applies.

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 / when-not-to-use guidance and no named alternative. With several backup-adjacent siblings (backup_schedule, managed_db_snapshot_create, restore, restore_to), the description does nothing to route the agent, so the agent must guess from names 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, destructiveHint=false, so safety is covered. The description adds genuine value beyond them: the URL is short-lived/signed, and it enumerates the portability formats (pg_dump, mysqldump, mongodump, redis rdb). This is useful behavioral context, though it doesn't address auth/permission requirements explicitly.

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 front-loaded sentences that lead with the core action. The final sentence carries mild marketing framing ('No data lock-in') but delivers real format information, so it mostly earns its place.

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

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

For a read-only URL-generating tool with no output schema, the description explains what the caller receives (a signed URL) and how to use it. Combined with annotations covering the safety profile, an agent has enough to call it correctly; only minor auth/prerequisite detail 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%, so all three parameters are already documented, including ttlSeconds bounds. The description only adds the vague notion of 'short-lived' without reinforcing the parameter semantics. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource: 'Generate a short-lived signed download URL for a backup file.' This clearly distinguishes the tool from a direct-download or in-place restore action. It doesn't explicitly name or contrast with siblings like nexusai_db_restore, so it falls short of full sibling differentiation.

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

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

The description gives an implied use case ('download the backup and restore offline'), which contextualizes when to reach for it. However, it never states when to prefer this over nexusai_db_restore or nexusai_db_backup_list, nor any exclusions. Usage is inferred rather than spelled out.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without description help. The description adds only the word 'available,' which mildly narrows the result set but does not explain pagination, ordering, or what a backup entry contains.

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

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

The description is a single, front-loaded sentence with no filler or repetition. Every word contributes to identifying the operation and its target.

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 simple single-parameter list tool with full schema coverage, clear read-only annotations, and no output schema to explain. The description is adequate for correct invocation, though it could mention whether all or only ready backups are returned.

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 serviceId parameter is fully documented in the schema as the DeploymentService ID. The description adds no further parameter semantics, so the baseline score of 3 applies when the schema does the heavy lifting.

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

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

The description states a clear verb ('List') and resource ('available backups for a database service'), so an agent immediately knows what the tool does. However, it does not distinguish this tool from closely related siblings such as nexusai_db_backup, nexusai_db_backup_schedule, or nexusai_db_restore, leaving the agent to infer the boundary from the name alone.

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

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

There is no explicit guidance on when to use this tool versus alternatives like nexusai_db_backup_schedule or nexusai_db_restore_to. The intended usage is implied by the simple list operation, but no conditions, 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 establish this is a non-read-only, non-destructive mutation, so the safety profile is covered. The description adds that the operation is a daily-schedule toggle but says nothing about side effects of disabling (are existing backups kept? does the schedule resume from today?), which is the main behavioral question for a toggle.

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 efficient sentence with no filler, and the core action is front-loaded. It is appropriately sized for a simple toggle, though it leaves room for one clarifying clause about sibling scope.

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, params are fully documented in the schema, and there is no output schema to explain. Still, for a mutation tool the definition omits whether disabling affects existing backups and how it relates to the manual backup/restore siblings, leaving meaningful gaps an agent would want closed.

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 enabled, serviceId, and the retentionDays floor/default behavior. The description adds no parameter detail at all — notably it never mentions retentionDays, which is the one parameter with non-obvious constraints. Baseline 3 applies when the schema carries the load.

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 pair ('Enable or disable') and resource ('daily automated backups for a database service'), which is more precise than the name alone. However, it does not distinguish itself from closely related siblings like nexusai_db_backup (on-demand backup) or nexusai_db_restore, leaving the agent to infer the schedule-vs-manual distinction.

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. It never says when an agent should toggle the schedule versus taking an on-demand backup with nexusai_db_backup, nor mentions any prerequisites (e.g., service must exist, must be running). The 'daily' cadence is the only implied usage context.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the result is a 'normalized schema graph', but says nothing about caching, what 'refresh' actually invalidates, or connectivity/permission requirements for the DB source.

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 it is perhaps terse enough that it omits useful routing context that would have earned its place.

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

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

For a read-only, two-parameter tool this is minimally adequate. With no output schema, the description should at least characterize what the 'normalized schema graph' contains and mention the caching/refresh implication, neither of which it does.

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% – both dbSourceId ('DB source UUID') and refresh ('Force cache refresh') are documented in the schema. The description adds no extra parameter meaning, 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 ('Get') and resource ('normalized schema graph for a DB source'), which is clearly distinguishable from siblings like nexusai_db_query_execute or nexusai_db_source_list. It does not explicitly name or contrast with those siblings, so it falls short of a 5.

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 alternatives such as nexusai_db_query_preview or nexusai_db_query_execute. The only usage hint is the implicit 'inspect before querying' workflow, which the agent must infer 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 declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, which is an unusual profile for something named 'propose'. The description's 'propose' framing helpfully implies no DDL is executed, resolving that ambiguity somewhat, but it says nothing about whether a proposal is persisted, whether it requires human approval, or what happens on a log with no identifiable error.

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-front-loaded sentence with the action and object stated immediately and zero filler. It is arguably too terse for a three-parameter workflow tool, but there is no wasted text.

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

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

With no output schema, the description carries the burden of explaining what a 'proposed fix' looks like (raw DDL? diff? warning?), and it does not. The safe-to-call character is implied but unconfirmed, leaving the agent to guess at the response shape and the propose/apply handoff.

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 dbSourceId, logSnippet, and the optional deploymentId are already fully documented in the schema. The description adds no syntax, format, or linkage detail beyond that (e.g. how deploymentId changes the analysis), 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 pair (analyze, propose) and resource (deployment log errors → DDL fix), so the agent knows this is an analysis-and-suggestion tool rather than an executor. It does not name the obvious sibling nexusai_db_apply_fix, so the boundary between proposing and applying must be inferred.

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 the apply_fix alternative that clearly follows this tool in a workflow. The agent gets no explicit signal about when this is the right call versus inspecting schema or querying directly.

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 destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is partly covered. The description still adds non-obvious behavior: exactly which operation classes need the confirmed flag and that dollar-quoted function/procedure bodies are supported. It does not mention affected rows, rollback behavior, or runtime limits beyond maxRows.

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: capability first, the confirmed gate second, a notable edge case (dollar-quoting) last. The DDL enumeration is list-heavy but each item is functional information; there is 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 destructive, no-output-schema tool, the description covers what can be executed and the confirmation gate that governs mutation. The main omission is relationship to the preview/apply-fix workflow and any hint about result or error shape, which an agent operating this tool would benefit from.

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 75%; sql, dbSourceId and confirmed are documented inline, leaving only maxRows undocumented. The description reinforces confirmed's gating role for DML/DDL (consistent with the schema) but adds no syntax or format guidance for the SQL string or the row cap. Baseline 3 is appropriate when the schema carries most of the load.

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 (execute SQL against an external DB source) and enumerates the statement classes it accepts (SELECT, DML, DDL variants). The word 'external' helps separate it from nexusai_managed_db_execute/nexusai_managed_db_query, but it never names the directly related sibling nexusai_db_query_preview, so the distinction is left implicit.

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

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

It gives a real precondition (DML and DDL require confirmed=true), which is actionable context for invoking it. However, it never states when to use this versus a sibling such as nexusai_db_query_preview or nexusai_db_apply_fix, nor that a preview step should precede execution. Usage is implied rather than guided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value by disclosing the mechanism (EXPLAIN plus safety analysis) and warning that destructive-looking DDL such as DROP FUNCTION/TRIGGER/VIEW/PROCEDURE is accepted and analyzed without being applied.

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, front-loaded with the core purpose and then the supported statement classes. The DDL enumeration is somewhat long but earns its place by clarifying that DROP-type statements are in scope for preview.

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 tool with no output schema and a read-only annotation profile, the description covers purpose, mechanism, and accepted inputs. The only shortfall is that it doesn't hint at what the preview returns (plan output vs. safety warnings), which would help an agent interpret 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 description coverage is 100% with only two required parameters (sql, dbSourceId), both documented in the schema itself. The description adds no parameter-level syntax, dialect, or format guidance, so the baseline 3 applies.

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

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

States a specific verb+resource combination (dry-run a SQL query) and clarifies the mechanism with EXPLAIN + safety analysis, plus the statement classes it accepts. It implicitly distinguishes itself from nexusai_db_query_execute via 'preview/dry-run' but never names that sibling, so sibling differentiation is left to inference.

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

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

'Dry-run' implies the pre-execution use case, but the description never states when to reach for this versus nexusai_db_query_execute, nor any prerequisites such as the query needing to be valid or the source being reachable. Usage is inferable but not 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 and readOnlyHint=false, so the safety profile is known. The description adds nothing beyond that: it never says existing data is overwritten, whether downtime occurs, whether the backup must be in the same region, or whether the operation is asynchronous.

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 efficient sentence with the action front-loaded and no filler. It is appropriately sized but leaves useful detail on the table.

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-read-only mutation with no output schema, the description should at minimum say what gets overwritten and what the agent should verify first. As written it is too thin for the risk level of the operation.

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

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

Schema description coverage is 100%, so both serviceId and backupId are already documented in the schema. The description adds no format, constraint, or cross-parameter semantics beyond that baseline.

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

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

States a specific verb (Restore) and resource (database service from backup), which is clearer than the bare name. However, it does not distinguish itself from the close siblings nexusai_db_restore_to or nexusai_managed_db_restore, 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?

No when-to-use guidance, no prerequisites (e.g. whether the backup must belong to the same service), and no mention of alternatives such as restore_to. The agent gets no routing help at all.

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 openWorldHint=false; the description reinforces this by stating 'Existing data on the target is overwritten' and adds constraints the annotations lack (same-org, postgres-to-postgres engine match). It omits auth requirements and whether the operation is reversible, but the annotation coverage lowers the bar.

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 purpose, then usage, then constraints. Every sentence carries information an agent needs; 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?

For a destructive two-parameter mutation with no output schema, the description covers purpose, trigger scenario, engine/org prerequisites, and the overwrite consequence. Only minor gaps remain (no note on reversibility or expected outcome), which is acceptable given annotation coverage.

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 backupId and targetServiceId are already fully documented, including the same-org constraint on the backup. The description adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (restore) and resource (backup) with precise scope: into a DIFFERENT deployment service in the same org. The 'different service' framing clearly distinguishes it from an in-place restore, though it never names the sibling nexusai_db_restore 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 concrete use case ('seed a new deployment from a snapshot of an old one') and a hard prerequisite (both services must use the same engine). It does not explicitly name the alternative tool (in-place restore) or state when NOT to use this one.

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 read-only safety, but the description adds valuable behavioral context by stating it returns each service ID and explaining that those IDs are inputs for backup/restore. It does not cover pagination, auth, or rate limits, but the added return-value context is meaningful beyond the annotations.

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

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

Two sentences, front-loaded with the core purpose and followed by the concrete downstream use. Every clause earns its place; there is no redundant or filler language.

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

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

Given a simple one-parameter list operation with annotations and no output schema, the description is nearly complete: it names what is listed, the return payload (service IDs), and the intended consumer tools. Minor gaps like pagination or output format are acceptable here.

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 single optional deploymentId parameter is fully documented in the schema. The description does not add any parameter-specific meaning beyond the schema's own explanation, which is the expected baseline when the schema carries the weight.

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 (database services, with examples like postgres, mysql, redis, mongo) and scopes it to services provisioned alongside deployments. This is clear, but it does not explicitly differentiate itself from the similar sibling nexusai_managed_db_list, so it falls short of a 5.

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

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

Explicitly says to use this tool to discover the serviceId required by nexusai_db_backup, nexusai_db_restore, and related tools. This gives clear when-to-use guidance, though it does not state when not to use it or name an alternative list tool.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description does not add behavioral context beyond the annotations, such as whether deletion is permanent, what dependent resources are affected, or whether authorization or detach steps are required.

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

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

The description is a single, front-loaded sentence with no wasted words. It is appropriately sized for a simple delete operation.

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

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

Given the simple one-parameter schema and destructive annotations, the description is minimally adequate. However, for a destructive resource deletion it could usefully state whether deletion is permanent or mention dependency constraints.

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 dbSourceId documented as a 'DB source UUID.' The description adds no parameter meaning beyond the schema, so the baseline of 3 applies for a well-covered single parameter.

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

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

The description states a specific verb and resource: 'Remove an external DB source.' It distinguishes an external DB source from related resources such as managed databases, but it does not explicitly differentiate itself from sibling tools like nexusai_db_source_list or nexusai_managed_db_delete.

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 no guidance about when to use this tool versus alternatives. It does not mention prerequisites, when deletion is appropriate, or how it relates to nexusai_db_source_list, detach operations, or managed database deletion.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered structurally. The description adds genuine value beyond that: credentials are managed externally, and the output IDs are the input keys for other MCP tools, which is behavioral context the 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?

Two sentences, nothing wasted. The core purpose is front-loaded, followed immediately by the operational constraint and the use of the result.

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 trivial no-argument list tool with no output schema, the definition covers purpose, the external setup prerequisite, and the purpose of the returned IDs. A brief note on what each source record contains (id, name, type) would close the only real gap, but the entry is adequate as written.

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 and schema coverage is 100%, so the schema fully documents the (empty) input. Per the baseline for zero-parameter tools, no compensating prose is required, and the description correctly does not invent any.

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 saved external DB sources') plus the scope ('for the organization'), so the agent knows this is a read-only inventory operation. It does not explicitly distinguish itself from nearby siblings like nexusai_db_services_list or nexusai_managed_db_list, which a reader must infer.

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 when-to-use context and an implicit when-not: connection registration and credential configuration happen outside chat via the dashboard or REST API, not through this tool. It also explains the downstream purpose of the result ('use the returned source IDs with MCP tools'). No explicit exclusions against sibling list tools, but the context is solid.

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=false, so the safety profile is conveyed structurally. The description adds one genuine behavioral trait beyond them — the change applies without restarting the deployment — but omits prerequisites, permissions, and what happens when both scheduling parameters are supplied.

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

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

A single front-loaded sentence that names the resource first and the non-restart guarantee second. No filler or redundant restatement of the tool 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?

Three fully documented parameters and no output schema mean the definition is nearly self-sufficient once the description's capability statement is read. It only lacks guidance on parameter interaction (absolute vs relative) and permission requirements, which is a minor 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%, so the schema already explains deploymentId, the ISO-or-null absolute timestamp, and the relative hours value. The description's 'extend, reduce' wording loosely maps to autoDestroyHours but adds no format or precedence detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb set (set/extend/reduce/disable) against a specific resource (auto-destroy schedule for a deployment), which is clearly distinct from sibling mutations like deploy_delete, deploy_stop, or deploy_redeploy. It does not explicitly name those siblings, so it stops short of a 5.

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 says what can be changed but never says when to reach for this tool versus deploy_delete, deploy_stop, or deploy_redeploy. The phrase 'without restarting it' hints at a non-disruptive alternative but is not framed as selection 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 destructiveHint=true and openWorldHint=false, so the agent knows this is an irreversible write. The description adds the useful nuance that it is permanent and frees resources, but says nothing about required permissions, cascading effects (e.g. attached domains, volumes, secrets), 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 front-loaded sentence of ten words with zero filler. Nothing is wasted and the key qualifier ('Permanently') comes first.

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 delete with annotations carrying the safety profile, the description is minimally sufficient. However, in a dense deploy_* sibling set, the absence of disambiguation against stop/auto_destroy and of any note about dependent resources leaves a real gap for a destructive operation.

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

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

Schema description coverage is 100% and the single parameter (deploymentId) is documented as a UUID in the schema. The description adds no format, sourcing, or validation detail beyond that, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('Permanently delete a deployment') and adds the consequence 'free its resources'. It is clear on its own, but it never distinguishes itself from close siblings like nexusai_deploy_stop or nexusai_deploy_auto_destroy, which an agent must choose between.

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 is given. With eight other deploy_* siblings, several of which also make a deployment go away (stop, auto_destroy, rollback), the description should say when deletion is the right call versus those alternatives. Only the word 'Permanently' hints at irreversibility.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds that the payload includes health status and recent health logs, but says nothing about the recency window, volume of logs, pagination, or whether it is a point-in-time snapshot.

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 its brevity comes at the cost of routing information that would earn its place.

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

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

No output schema exists, so the description must carry the burden of describing return values, and it only sketches them ('health check status and recent health logs'). Combined with zero sibling differentiation in a crowded deploy_* family, it is minimally adequate but incomplete.

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

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

Schema description coverage is 100% and the single parameter (deploymentId) is documented in the schema as a Deployment UUID. The description adds no extra meaning about the identifier's format, source, or accepted values, so 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 and resource plus the return contents ('Returns health check status and recent health logs for a deployment'). An agent knows what it does, but nothing distinguishes it from the closely related siblings nexusai_deploy_status and nexusai_deploy_logs, which sound like they overlap heavily.

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 over nexusai_deploy_status or nexusai_deploy_logs, and no stated prerequisites or conditions. The description leaves the agent to guess which of the three deployment-diagnostic tools to pick.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only the word 'recent', without disclosing ordering, truncation, or whether logs are streamed or historical — modest added value against a low bar.

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, which is appropriate for a simple read tool. It is arguably under-specified rather than over-long, so it sits just below the top of the range.

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 low-complexity read tool with full schema coverage, complete annotations, and no output schema (so return-format explanation is unnecessary), the description covers the essentials. The only real gap is the absence of guidance on when logs are the right signal versus status or health.

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

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

Schema description coverage is 100%, so all three parameters (deploymentId, type with build/runtime, limit with max 1000) are fully documented in the schema. The description adds no syntax, default, or format detail beyond it, 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 (returns) and resource (log lines) scoped to a deployment, which clearly separates it from siblings like nexusai_deploy_status and nexusai_deploy_health that report state rather than output. It does not, however, name any sibling explicitly, so the differentiation is inferable 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?

The description offers no when-to-use guidance and no exclusions; it never tells the agent to prefer this over nexusai_deploy_status or nexusai_deploy_health when diagnosing a deployment. Usage is only weakly implied by the word 'logs'.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds substantial context beyond that: which resources are preserved (managed databases, volumes, secrets, env vars) and how env vars can be overridden. It does not cover auth requirements or rate limits, but the preservation/overwrite semantics are valuable.

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 dense sentences, front-loaded with the default in-place behavior before the conditional new-deployment case. Every clause contributes, though the parenthetical override note is slightly compressed given the number of fields it references.

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

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

For a mutation tool with no output schema, the description adequately explains the in-place-vs-new decision and preserved state. However, with a nested 11-property overrides object that is almost entirely undocumented in both schema and description, an agent lacks guidance on most override fields, leaving a meaningful 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 0%, so the description must carry the burden. It adds meaning for overrides.envVars and names name/provider/code/dockerfile as new-deployment triggers, but leaves the other override fields (region, framework, displayName, healthCheckUrl, autoDestroyHours, etc.) and the required deploymentId entirely unexplained. It partially compensates but leaves clear gaps.

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 ('Rebuild a deployment IN PLACE') and precisely defines the default scope: same deployment id and URL. It further distinguishes its behavior from nexusai_deploy_create by stating that a NEW deployment only happens under specific override conditions, so an agent can tell the two apart 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?

It gives clear context for when the in-place behavior applies versus when a new deployment is spun up (overrides set name/provider/code/dockerfile, or non-repo sources). It does not explicitly name sibling alternatives like deploy_rollback or deploy_create, so it stops short of full 'when-not' guidance, but the conditional logic is well conveyed.

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 openWorldHint=true, so the safety profile is covered. The description usefully adds that rollback is implemented as a redeployment of a prior revision rather than an in-place restore, but it never says what happens to the currently running deployment, whether the action is reversible, or what permissions are required.

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 appropriately sized, though it is on the thin side for a destructive operation, which is a completeness issue rather than a verbosity one.

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 mutation with no output schema, the schema carries the argument detail, but the description omits key operational facts: impact on the running deployment, reversibility, and prerequisites. Adequate but with clear gaps.

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

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

Schema coverage is 100%, so both parameters are already documented; baseline is 3. The phrase 'a previous deployment revision' weakly implies what happens when targetDeploymentId is omitted (default to the prior revision), but this is left to inference rather than stated.

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 (rollback) and resource (deployment) and explains the mechanism — redeploying a previous revision in the same project. It does not explicitly distinguish itself from the close sibling nexusai_deploy_redeploy, which shares nearly the same mechanism, so it stops short of a 5.

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 explicit contrast with alternatives such as nexusai_deploy_redeploy or nexusai_deploy_delete. The agent must infer the rollback use case 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 this is a write operation (readOnlyHint=false) that is non-destructive and closed-world, so the safety profile is covered. The description adds the deployment-must-be-running precondition and the effective replica range, but says nothing about the effect of scaling down (replica termination, rollout behavior) or whether the operation is immediate.

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 constraint; no filler, no redundancy.

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, fully-documented, no-output-schema tool with clear annotations, the description covers what an agent needs to invoke it. The remaining gap is behavioral outcome (what scaling does to running replicas), which is minor at this complexity level.

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 deploymentId (UUID) and replicas (1-10 with min/max) documented in the schema itself, so the baseline is 3. The description merely restates the bound already encoded in the schema and adds no format or identifier guidance.

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 (scale) plus resource (running deployment) and the target value, which clearly separates it from siblings like nexusai_deploy_start, _stop, and _redeploy. It does not, however, explicitly name or contrast itself with any alternative, so it falls short of a 5.

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 word 'running' implies the prerequisite that the deployment must already be started (vs. nexusai_deploy_create/start), which is useful but only implied. There is no explicit when-to-use/when-not-to-use statement or reference to sibling 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 declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive mutation. The description adds the state-transition precondition (must already be stopped) but says nothing about side effects, resulting state, or permissions required.

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 zero waste and the action front-loaded. It is appropriately sized but borders on under-specification rather than true 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?

For a simple one-parameter action tool with annotations and no output schema, this is adequate but thin. It omits what the resulting deployment state is or whether the operation is synchronous, which would help an agent act 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 a single deploymentId parameter documented as 'Deployment UUID.' The description adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Start) and resource (deployment) with the precondition that it acts on a stopped deployment. Clear enough to distinguish from the sibling nexusai_deploy_stop, though it does not name that counterpart 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?

The phrase 'stopped deployment' implies the precondition for use, but there is no explicit when-to-use guidance or routing to alternatives like nexusai_deploy_redeploy or nexusai_deploy_rollback for other state changes.

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, openWorldHint=false and destructiveHint=false, covering the safety profile. The description adds nothing beyond this – no note on auth requirements, rate limits, or what 'status details' actually includes.

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 or redundancy. It is efficient, though the brevity partly reflects under-specification rather than tight curation.

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 read tool this is nearly sufficient, and no output schema exists so return values need not be explained. But the vague 'status details' plus unresolved overlap with deploy_health means an agent still lacks enough to choose 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 deploymentId documented as a 'Deployment UUID.' The description adds no further meaning, 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 clear verb and resource ('Returns status details for a deployment'), so an agent knows it retrieves deployment status. However, it does not distinguish itself from close siblings like nexusai_deploy_health or nexusai_deploy_list, leaving the boundary between 'status' and 'health' ambiguous.

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 offers no when-to-use context, no prerequisites, and no reference to alternatives such as deploy_health or deploy_list. An agent must infer selection criteria from tool names 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=false and destructiveHint=false, so safety is covered. The description usefully adds the key behavioral fact that the deployment is preserved rather than removed, clarifying the difference between a stop and a delete. It does not say whether the stopped state is resumable or what is returned, 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?

A single sentence with zero filler, front-loading the action and the crucial non-destructive qualifier. Nothing could be trimmed without losing meaning.

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

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

For a one-parameter tool with annotations covering the safety profile and no output schema, this is nearly complete. A brief note on resumability (vs deploy_start) or the resulting state 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?

Only one parameter (deploymentId) and schema description coverage is 100%, so the schema already carries the meaning. The description adds no format, identifier-source, or lookup guidance beyond what is documented, matching the baseline for a fully-covered 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 ('stop') plus resource ('a running deployment') with an explicit scope qualifier ('without deleting it'). This lets an agent distinguish it from nexusai_deploy_delete and nexusai_deploy_auto_destroy without inspecting 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 is implied by the 'running deployment' precondition, but there is no explicit when-to-use guidance or named alternative (e.g. when to stop vs delete vs auto-destroy, or that start can resume). The agent must infer routing from sibling names 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=false, destructiveHint=false, and openWorldHint=false, so the description need only add context beyond that — and it adds none. It doesn't mention that the domain stays unverified until DNS records are confirmed, what happens if the domain is already attached, or whether the operation is idempotent. The openWorldHint=false annotation is also worth noting: registering an external domain name arguably reaches outside the closed system, so the description could have clarified the actual scope.

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

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

A single front-loaded sentence with zero filler, which is appropriately sized. It is arguably over-terse for an operation that appears to have a multi-step lifecycle, but it wastes no words.

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

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

This is a mutation with no output schema and minimal annotations, so the description carries real explanatory burden. It omits the likely verification requirement, doesn't state what the caller gets back, and gives no failure or conflict behavior — an agent cannot confidently complete the workflow from this 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% with only two parameters, both required and both documented in the schema (domain name with example format, deployment UUID). The description adds no format or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Add a custom domain to a deployment.' This is clear and action-oriented. It does not, however, distinguish itself from adjacent siblings like nexusai_domains_verify or nexusai_domains_remove, so differentiation comes from the tool name rather than the description.

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

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

The description gives no when-to-use context, no prerequisites (e.g. the domain must already point at the platform's DNS), and no mention of the follow-up verification step implied by the sibling nexusai_domains_verify. The agent must infer the workflow 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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the scoping fact that results are per-deployment, offering little beyond the annotations and name.

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. Efficient, though its brevity leaves gaps rather than being genuinely economical with rich 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 simple read-only list tool with one fully documented parameter and annotations covering the safety profile, the description is adequate. No output schema exists, but for a plain listing operation the missing return-format detail 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 description coverage is 100% and there is only one parameter (deploymentId, documented as 'Deployment UUID'), so the schema carries the parameter burden. The description adds no format or syntax detail beyond what the schema provides, 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 clear verb (List) and resource (custom domains) with the scoping constraint 'attached to a deployment'. This distinguishes it reasonably from domains_add/remove/verify, though it doesn't explicitly name those siblings as alternatives.

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 the sibling tools (domains_add, domains_remove, domains_verify) that an agent might confuse it with. The agent must infer that this is the read-only listing 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered, but the description adds nothing beyond them: it does not say whether removal is reversible, whether DNS/verification records are cleaned up, whether the domain is detached only from the deployment or deleted outright, or what permissions are required.

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, appropriate for a two-parameter tool. It is arguably too terse for a destructive operation, which keeps it from 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?

Annotations carry the destructive safety profile and the schema fully documents both parameters, so the minimum is met. However, for an irreversible removal the description omits any warning, side-effect disclosure, or post-removal state, leaving ambiguity about whether the domain is detached or destroyed.

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 required UUID parameters documented in the schema, so the baseline is 3. The description adds no format, ordering, or lookup guidance beyond what the schema already states.

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

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

States a specific verb (Remove) and resource (custom domain) and clarifies scope as removal from a deployment, so an agent can distinguish it from nexusai_domains_add/list/verify. It does not explicitly name those siblings or contrast behavior, so it stops short of a 5.

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 nexusai_domains_verify or a hypothetical domain deletion, and no preconditions or ordering constraints are given. An agent must infer usage entirely from the tool name and siblings.

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

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

Annotations already disclose readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the agent knows this is a non-destructive action that reaches outside the system. The description's mention of DNS adds context that explains the open-world trait, but it says nothing about whether verification is asynchronous, what happens on failure, or whether it can be safely retried.

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; the action verb and target are the first things read. Nothing could be removed without losing meaning.

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

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

For a mutation-style, open-world operation with no output schema, the description omits essential context: prerequisites (domain added, DNS records propagated), async vs. synchronous behavior, and what a successful or failed verification means. The annotations cover the safety profile but not the operational flow.

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% (both domainId and deploymentId are documented as UUIDs in the schema), so the schema carries the parameter burden. The description adds no additional meaning about how the two identifiers interact or which one scopes the verification.

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 pairs a specific verb ('Trigger DNS verification') with a clear resource ('custom domain'), so an agent knows exactly what action is performed. It is readily distinguishable from the domains_add/list/remove siblings, though it never names or contrasts them explicitly.

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

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

No when-to-use guidance is given: it does not state that the domain must first be added via nexusai_domains_add, that DNS records must already be configured, or when a re-verification is appropriate versus other domain operations. The agent must infer all preconditions.

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 safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description clears it by disclosing what actually gets written (connection env vars) and the operational consequence that a redeploy is required. It stops short of saying whether existing env vars are overwritten or whether detach reverses it, so it is not fully complete.

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, front-loaded with the core action and followed by the key caveat. Every clause earns its place with no filler.

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

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

For a small mutation tool with matching annotations and no output schema, the description covers the essential effect and the redeploy requirement. It leaves notable gaps: no mention of reversibility via detach, no statement about overwriting existing env vars, and no clarification of the required identifiers.

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

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

Schema coverage is only 33%: envPrefix is documented in the schema while deploymentId and managedDatabaseId have no descriptions anywhere. The description mentions injecting vars into a deployment but adds no meaning about the two required IDs or how envPrefix renames the listed env vars, so it fails to compensate for the coverage gap.

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

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

The description gives a specific verb and resource mechanism: it injects connection env vars into a deployment, and even enumerates the env var names. That is clear, but it describes the implementation rather than the 'attach' concept and never names the natural inverse sibling nexusai_managed_db_detach, so an agent must infer the pairing.

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

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

Usage is implied by 'into a deployment' plus the 'Requires redeploy' prerequisite, which is genuine guidance about when the effect materializes. However, there is no explicit when-to-use statement, no when-not-to-use, and no routing to alternatives such as detach.

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 the read-only, non-destructive, closed-world profile, so the bar is lower; the description adds the key behavioral fact that credentials are deliberately excluded and where they live instead, which prevents an agent from hunting for secrets via this tool. It doesn't mention pagination or response shape, but for a single-object read that is minor.

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, front-loaded with what is returned; the credential caveat and the sibling redirect each earn their place 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 carries the return-value burden and does so by naming the fields returned, plus it clarifies the credential boundary and the alternative tool. The only missing piece is how/where to source the managedDatabaseId.

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 required parameter (managedDatabaseId) with 0% schema description coverage, so the schema adds nothing. The description supplies no information about where to obtain the ID or its expected format (e.g., from nexusai_managed_db_list), leaving a real gap even if the parameter is largely self-evident.

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 ('Return non-secret database metadata') and enumerates the fields returned (engine, status, host, port, database name), which also corrects the potentially misleading tool name 'connection'. It names nexusai_managed_db_attach as the contrasting operation, though it doesn't differentiate itself from siblings like nexusai_managed_db_list that likely also surface database info.

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

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

Gives clear context for when to use this tool (fetch non-secret DB metadata) and explicitly redirects to nexusai_managed_db_attach for configuring an app server-side, plus points to the dashboard for credentials. It lacks any explicit exclusion relative to other read siblings such as nexusai_managed_db_list.

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 mark this as a non-read-only, open-world, non-destructive mutation, but the description adds substantive traits the annotations cannot convey: paid-plan requirement, credentials generated server-side and never returned via MCP (view in dashboard), and async provisioning requiring status polling until AVAILABLE. These are genuinely useful operational disclosures.

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 purpose before provider guidance, then warnings (paid plans, credentials), then the async workflow. Every sentence carries distinct information, though the provider sentence is dense and slightly crowded with parenthetical 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?

For an 11-parameter mutation with no output schema, the description covers the key operational facts: credential non-return, async provisioning, and status-gated attachment. It does not state what the create call itself returns (e.g., identifier/status fields), which the absent output schema leaves as a minor 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 91%, so the schema already documents parameter meaning, enums, defaults, and provider/engine constraints in depth. The description only lightly reinforces provider choice (NEXUS_DOCKER vs cloud) and adds nothing parameter-specific beyond what the schema provides; 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 standalone database') and immediately distinguishes it from deployment-attached databases and from the sibling attach/list tools ('independent of any deployment, then attach it to apps'). An agent can identify the operation without opening the schema.

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

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

Gives clear selection context: use NEXUS_DOCKER for a DB on NEXUS AI (Postgres/Redis) or a cloud provider for a managed cloud instance, plus the 'Paid plans only' prerequisite. It does not explicitly exclude or contrast against siblings like nexusai_deploy_create or nexusai_managed_db_attach, 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 already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description still adds value beyond them: it explicitly says the data is permanently destroyed and imposes a human-in-the-loop confirmation (the caller must not fill in confirmDatabaseName on the user's behalf), which no annotation conveys.

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 irreversible outcome. Each sentence carries information, though the description is terse enough that it leaves some behavioral questions (prerequisites, async completion) unaddressed.

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, no-output-schema mutation tool this covers the essentials (permanence, data loss, human confirmation, and the force behavior is in the schema), but it omits notable operational context: whether the database must first be detached or snapshotted, and whether deletion is synchronous or asynchronous.

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 67%: force and confirmDatabaseName are documented in the schema, and the description usefully reinforces that confirmDatabaseName is the user-typed name. managedDatabaseId has no description anywhere, but its meaning is self-evident. The description roughly matches the schema rather than substantially extending it.

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

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

States a specific verb+resource ('delete a managed database instance') and the adverb 'Permanently' distinguishes it from the sibling nexusai_managed_db_detach and snapshot/restore tools. An agent can tell that this is irreversible removal rather than detachment without opening the schema.

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

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

Usage is implied (this is the tool for permanently removing a database), and it carries one genuine usage rule: the person must type the name themselves. However, it never names alternatives such as nexusai_managed_db_detach or snapshotting first, so the when-to-use-vs-sibling decision is left 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=false, destructiveHint=false, openWorldHint=false, covering the safety profile, yet the description still adds a genuinely non-obvious behavioral fact: the change is deferred to the next deploy rather than applied immediately. It omits other relevant behavior such as whether existing env vars are removed, whether a redeploy is required, and whether prior deployments are affected, so a 3 is appropriate.

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 zero filler that leads with the concrete action. It is efficient, though arguably terse given the operation's implications.

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 state-changing tool with no output schema, 0% parameter coverage, and no annotation detail beyond the safety hints, the agent is left without prerequisites, side effects on existing deployments, or confirmation of whether data is preserved. The deferred-effect note helps but does not make the definition 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 description coverage is 0% and neither required parameter (managedDatabaseId, deploymentId) is mentioned or explained in the description. The parameter names are largely self-descriptive, but the description does nothing to compensate for the total lack of schema documentation.

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 concrete effect (stops injecting database connection env vars) which unambiguously identifies this as the inverse of nexusai_managed_db_attach. It is clear what the tool does, though it describes the mechanism rather than naming the 'detach' operation directly and does not restate which database/deployment pairing applies.

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

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

There is no when-to-use guidance, no prerequisite (e.g. must currently be attached), and no explicit reference to the attach sibling as the reversing operation. The agent must infer usage entirely from the tool name and mechanism.

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, so the safety profile is known. The description adds non-obvious context beyond that: the manage-scope auth requirement, the fact that SQL is safety-checked, and the preview-by-default behavior when confirmed is omitted. It could go further on irreversibility or error behavior, but the added value is real.

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 verb/resource, then auth requirement, then the critical preview-vs-execute distinction. No filler; each sentence carries distinct, actionable 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?

For a destructive mutation tool with no output schema and only 50% param coverage, the description covers the essentials an agent needs: scope, safety check, and the confirm-to-execute gate. It is slightly thin on identifying managedDatabaseId and on the params array, which is why it is not a full 5.

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

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

Schema description coverage is only 50%: confirmed and params are documented in the schema, while sql and managedDatabaseId are not. The description reinforces the confirmed semantics (preview without it) and characterizes sql as write/DDL, but adds little for managedDatabaseId or the params array, so it only partially compensates for the coverage gap.

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

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

States a precise verb+resource+scope: run a write or DDL statement (INSERT/UPDATE/DELETE/CREATE/ALTER) against a managed database. This clearly separates it from the read-oriented siblings like nexusai_managed_db_query and nexusai_db_query_preview without the agent needing to open 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 real operating guidance: manage scope is required and the statement is only previewed unless confirmed=true, which tells the agent how to safely stage the call. It does not, however, name an alternative tool or state when a different sibling should be chosen instead.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description contributes the org-scoping constraint and the RDS resource type, but says nothing about pagination or result ordering for what could be a large listing.

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 scope qualifier first and zero filler. Nothing could be removed without losing 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?

For a zero-parameter read-only listing with no output schema, the description is close to sufficient; annotations carry the safety profile. It stops short of 5 because it neither hints at the shape/volume of results nor bounds the listing (e.g. pagination or filtering limits on org scope).

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 and the baseline is 4. The description correctly does not invent parameter guidance for a no-arg tool.

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 org-scoped managed cloud databases") and narrows the resource type to AWS RDS instances, so an agent knows exactly what is returned. It does not, however, distinguish itself from close siblings such as nexusai_db_services_list or nexusai_db_source_list, which an agent could easily confuse it with.

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

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

No when-to-use, when-not-to-use, or alternative routing is given. The "managed_db" vs "db_services" vs "db_source" distinction is left entirely to inference from the tool name, which is exactly where a sibling-aware sentence would have earned its place.

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 and destructiveHint, so the safety profile is covered; the description still adds real value by noting that writes and DDL are rejected, that SQL is safety-checked, and that the tool connects either directly or through the in-VPC/VNet proxy. It stops short of describing the return shape, pagination, or row 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?

Three short sentences, front-loaded with the core action and the read-only constraint, with no filler or repetition. Every sentence carries a distinct fact.

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 tool with no output schema, two undocumented required parameters, and ambiguous siblings, the description leaves key gaps: the return format is unexplained, parameter formats are absent, and the distinction from nexusai_managed_db_execute is missing. Annotations carry safety, but the rest of the burden is unmet.

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

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

Schema description coverage is only 33% (just 'params'), and the description adds nothing about any parameter: it never explains what 'sql' accepts, what 'managedDatabaseId' identifies, or how positional 'params' are bound to placeholders. With this coverage gap, the description should compensate and does not.

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 ('Run a read-only SELECT against a managed database') and clarifies the scope (no writes/DDL). However, it never distinguishes this tool from the closely named sibling nexusai_managed_db_execute, so an agent cannot tell which one to pick without inspecting both 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?

There is no when-to-use guidance and no mention of alternatives, despite several overlapping siblings (nexusai_managed_db_execute, nexusai_db_query_execute, nexusai_db_query_preview, nexusai_db_inspect_schema). The connection-mode note (public vs private proxy) is informational but does not tell the agent when to choose this tool over another.

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=false and readOnlyHint=false; the description reinforces this by stating the operation is non-destructive and leaves the source database unchanged, which is genuinely useful for an agent worried about data loss. It stops short of describing provisioning time, naming conflicts on newName, 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?

Two short sentences, zero filler, with the NEW-instance/non-destructive point front-loaded. Every clause earns its place.

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

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

Covers the single most important semantic (a new instance is created and the source is safe) for a three-param mutation with no annotations on return behavior and no output schema. It omits any guidance on the undocumented identifiers or the expected result of the call, leaving the definition minimally viable.

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

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

Schema coverage is only 33%: newName has a description, but snapshotId and managedDatabaseId are entirely undocumented, and the description adds nothing about any parameter. With the schema covering only one of three params, the description fails to compensate for the gap.

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

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

States a specific verb (Restore) and resource (snapshot into a managed database instance) plus the key qualifier that the target is a NEW instance. This differentiates it in spirit from the sibling restore tools (nexusai_db_restore, nexusai_db_restore_to), but it never names them, so the differentiation is implicit rather than explicit.

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

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

The description implies when to use it (you want a copy of a snapshot in a separate instance rather than an in-place restore) but gives no explicit when-not conditions and does not point to alternatives such as nexusai_db_restore_to or nexusai_managed_db_snapshot_create. Usage is inferable, not stated.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is already partly covered. The description adds genuinely useful behavior beyond that: the operation is asynchronous and completion must be detected by polling the snapshot list, which an agent could not infer from the annotations or 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 short sentences, zero filler, with the core action front-loaded and the async/polling caveat immediately after. Every clause earns its place.

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

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

With no output schema, the description does well to state that results are asynchronous and retrievable via the snapshot list. But for a mutation tool with completely undocumented parameters, it omits what a snapshot affects (e.g. potential I/O impact, retention, permissions) and what 'notes' does, leaving gaps an agent cannot fill from structured fields.

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

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

Schema description coverage is 0%: neither 'notes' nor 'managedDatabaseId' is documented in the schema, and the description never explains either. In particular the free-form 'notes' parameter has no stated purpose or constraints, so the description fails to compensate for the coverage gap.

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

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

States a specific verb and resource: 'Take a point-in-time snapshot backup of a managed database (AWS RDS snapshot)'. The parenthetical pins the concrete backing service, and the reference to polling the snapshot list implicitly separates it from nexusai_managed_db_snapshot_list and nexusai_managed_db_restore. It does not explicitly contrast with the nexusai_db_backup family, which shares the backup vocabulary.

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?

'Async; poll the snapshot list until available' gives clear post-invocation guidance and names the sibling to poll. However, there is no statement of when to choose this over nexusai_db_backup / nexusai_db_backup_schedule or any prerequisite (database must be available, size/time implications). Usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond them: no pagination behavior, no result ordering, no permissions, and no indication of what happens with a nonexistent database id.

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, front-loaded sentence with no filler or repetition. It is efficient, though its brevity stems partly from under-specification rather than tight writing.

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 (one required param, read-only, no output schema), and the description covers the basic intent, so it is minimally viable. It still omits the parameter meaning and any return-shape or volume expectations, which for a list endpoint an agent would benefit from knowing.

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

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

Schema description coverage is 0%, so the description carries the burden for the single required parameter, yet it never mentions managedDatabaseId, its format, or where to obtain it. A generic listing of 'a managed database' is not enough to compensate for the uncovered parameter.

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

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

The description states a specific verb (List) and resource (snapshot backups) scoped to a managed database, which separates it from the sibling nexusai_managed_db_snapshot_create. However, it does not explicitly contrast itself with the similar nexusai_db_backup_list, so the agent must infer the managed-vs-unmanaged distinction.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as nexusai_db_backup_list or nexusai_managed_db_restore. The agent gets no explicit routing signal beyond the tool name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the tenant-scoping detail, which is real context, but says nothing about pagination, ordering, or result size behavior.

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

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

A single front-loaded sentence with zero filler. It is appropriately sized for a trivial list operation, though it is terse enough that some useful context was omitted rather than 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?

For a simple read-only list tool with full annotation coverage and a fully documented parameter, this is minimally adequate. With no output schema, the description could have indicated what a project record contains or how results are ordered, which would help an agent chain into project-scoped tools.

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

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

With one parameter and 100% schema description coverage, the schema already fully documents 'limit' including its default and bounds. The description adds no additional meaning, 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 (Lists) and resource (projects) with a scope qualifier (current tenant), which is enough to identify the tool. It doesn't explicitly differentiate itself from siblings, though none of the listed siblings also list projects, so ambiguity is low.

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

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

There is no guidance on when to use this tool, what the tenant scoping means in practice, or how to get a project identifier needed by other tools. Usage is only implied by the name and one-line description.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful scoping context that results are filtered to the tenant plan, but does not disclose auth requirements, rate limits, or return shape details.

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 contributes to stating what the tool returns and the scoping constraint.

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 whose annotations already cover safety, the description is complete enough to invoke correctly. The only minor gap is that no return format or pagination behavior is described, though no output schema exists and complexity is very low.

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 has zero parameters, so the baseline is 4. There are no parameter semantics for the description to clarify, and the description appropriately does not invent any.

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 ("Lists") and resource ("deployment providers") with a clear scope ("allowed for the tenant plan"). It does not explicitly differentiate from sibling list tools, but the resource is distinct enough that an agent can tell it apart from tools like nexusai_deploy_list.

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

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

There is no when-to-use guidance, no alternatives named, and no exclusions. The agent can infer the purpose from the description text, but it must decide on its own when this tool is appropriate versus other list or deploy 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 destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not say whether deletion is permanent, whether dependent deployments/buckets break, or whether any permission is required.

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 padding. It is efficient, though the brevity contributes to the missing behavioral and usage detail rather than being a strength in itself.

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-recoverable-sounding operation with no output schema and no annotations covering consequences, the description should say what is destroyed or affected. It omits dependency impact, confirmation expectations, and the meaning of the returned result, leaving meaningful gaps.

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

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

There is a single parameter with 100% schema description coverage ('Secret UUID.'), so the schema carries the full burden. The description adds no format, sourcing, or resolution guidance beyond what the schema supplies, making the baseline 3 appropriate.

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

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

States a specific verb (delete) and resource (secret) with scope (organization), which cleanly distinguishes it from nexusai_secrets_list. It does not explicitly name a sibling alternative, but the operation 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 use this versus other lifecycle tools, no prerequisites (e.g., does the secret need to be detached from deployments first?), and no warning about confirmation or irreversibility. The agent is left to infer everything.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: only names and metadata are exposed, secret values are not returned, and value management happens in an authenticated external vault.

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, both earning their place: the first defines scope, the second handles the routing constraint. The most important scoping fact ('names and metadata only') is front-loaded.

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

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

With no output schema, the description carries the return-value burden and does so adequately by stating that only names and metadata are returned. Pagination, ordering, and empty-list behavior are unspecified, which is the only remaining gap for an otherwise simple zero-param read.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool is 4. Nothing in the schema or description is misleading.

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 ('Lists secret names and metadata only'), and the phrase 'names and metadata only' meaningfully scopes what is returned versus a hypothetical value read. It does not explicitly name the sibling it complements (nexusai_secrets_delete), so it falls short of full sibling differentiation.

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

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

The second sentence clearly routes create/update work away from chat to the secrets vault URL, which is an explicit 'do this elsewhere' directive. However, it gives no guidance on reading the results or on how this list relates to nexusai_secrets_delete.

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, and openWorldHint=true, so the mutation/scope profile is known. The description's contribution is the sensitive-data prohibition, which is genuinely useful operational guidance but is largely repeated verbatim inside the schema's description property. It adds no return-behavior or permission context beyond that.

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, purpose front-loaded, followed by usage trigger and a data-safety warning. Nothing is wasted, though the PII sentence duplicates content already in the schema.

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 mutation tool with no output schema and full annotation coverage, the definition supplies purpose, trigger, and the key data-handling constraint an agent must respect. Missing only a note on what submission returns or how to follow up via the reply sibling.

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 two enum constraints documented, so the schema already carries full parameter meaning. The description does not elaborate on the subject/category/priority fields or defaults, 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?

The description states a specific verb and resource ("Submit a new support ticket") and the scope ("new") that inherently separates it from nexusai_support_ticket_reply, _get, and _list. However, it never names those siblings explicitly to reinforce the distinction, which is what separates a 4 from a 5.

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

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

It gives clear when-to-use context ("platform issues, plan questions, or ... help with a deployment"), which is concrete guidance most definitions lack. It stops short of naming when NOT to use it or pointing at the reply/list siblings for follow-ups, so no exclusion criteria are 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuine value by disclosing the return content ('full details and message thread'), which matters because there is no output schema to reveal it. It does not cover pagination or thread-size limits, 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?

A single front-loaded sentence with zero filler. The payload (details plus message thread) is stated immediately, and nothing is repeated from the schema or annotations.

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

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

For a read-only single-ticket fetch with one fully documented required parameter and safety annotations, the description plus structured fields are nearly sufficient, and it helpfully names the return content in the absence of an output schema. Only missing piece is guidance on how to obtain the ticketId or handle a not-found 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?

There is a single required parameter (ticketId) with 100% schema description coverage, so the schema fully documents its type and meaning. The description adds no format, ID-source, or lookup guidance beyond 'a support ticket'. 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 clear verb ('Get') and resource ('support ticket') and specifies the payload ('full details and message thread'). It is distinguishable from the sibling list/create/reply tools by the singular 'a support ticket', but it never explicitly contrasts itself with nexusai_support_ticket_list or reply.

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

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

There is no when-to-use guidance, no statement of prerequisites (e.g. needing a ticketId from the list tool), and no mention of alternatives such as nexusai_support_ticket_list for browsing tickets. The agent must infer usage entirely from the name and schema.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the org-scoping detail and says nothing about pagination behavior or result volume, which the schema leaves implicit beyond defaults.

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 zero waste; the core purpose is front-loaded and the optional filter follows. Nothing is padded 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 read-only list tool with full annotation coverage, a fully documented schema, and no output schema, the description supplies enough to call it correctly. It could mention pagination defaults, but the schema already carries those.

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 page, limit, and status are fully documented in the schema. The description's mention of the status filter merely repeats that. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb ('List') and resource ('support tickets') scoped to 'your organization'. The verb alone distinguishes it from the sibling create/get/reply tools, though the description does not name those alternatives 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?

'Optionally filter by status' describes a parameter, not when to choose this tool over nexusai_support_ticket_get or nexusai_support_ticket_create. There is no stated condition, prerequisite, or exclusion to guide selection.

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

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

Annotations already declare this is a non-read-only, non-destructive, open-world write. The description adds a genuinely useful constraint not present in the structured fields: the list of sensitive data that must not be included. It still omits whether the reply is customer-visible, whether it triggers notifications, or whether replies can be edited or deleted.

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 with the action front-loaded and the compliance constraint second. The sensitive-data enumeration is long but each item earns its place as an enforceable rule rather than 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 two-parameter mutation tool with annotations covering the safety profile and a fully documented schema, the description is serviceable but thin. It lacks any indication of the reply's visibility, notification behavior, or ticket-state preconditions, which an agent would need to invoke it confidently.

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

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

Schema description coverage is 100% and both parameters are documented in the schema (message as the reply body, ticketId as a support ticket UUID). The description adds no format, length, or ID-resolution detail beyond what the schema already states, 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 ("add a reply") and resource ("existing support ticket"), clearly distinct from the sibling create/list/get ticket tools. It doesn't explicitly name a sibling it should be used instead of, so it stops short of a 5.

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

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

The phrase "existing support ticket" implies a prerequisite (the ticket must already exist), and the sensitive-data prohibition gives a usable compliance rule. However, there is no guidance on when to reply versus creating a new ticket, nor any note about ticket state (open/closed) restrictions.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds only that the payload includes quotas and deployment counts; with no output schema this is modest added value, and it says nothing about time windowing, freshness, or org scoping rules.

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