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

No annotations provided, so description carries full burden. It discloses that this is a pure helper (no API call), the URL structure, that /start issues a 302 redirect to dashboard /claim page, and explicitly states the MCP server cannot complete the claim—it requires a browser session. All behavioral traits are transparent.

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

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

Well-structured with bullet points for usage guidelines, front-loaded with purpose. Every sentence is informative and necessary. No fluff or 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?

Despite no output schema, the tool is simple and the description covers input, behavior, limitations, and how to present the result. For a helper tool returning a URL, this is 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 coverage is 100%, so baseline is 3. The description adds extra context beyond the schema: clarifies the JWT comes from create_* tools' 'upgrade_jwt' field or raw JWT from 'upgrade' URL, and emphasizes it is required. This adds meaningful value, raising the score to 4.

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

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

The description clearly states it transforms a JWT into a claim URL, explicitly calling it a pure helper that builds a URL from the JWT. It distinguishes itself from sibling tools like claim_token (programmatic) and create_* tools (provisioning) by specifying its unique purpose.

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 explicit when-to-use conditions: after provisioning, user wants to keep resource past 24h, or wants a clickable URL. Also gives a when-not-to-use: if agent has user's email and JWT, use claim_token instead. This is comprehensive 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?

With no annotations, the description carries the full burden. It discloses key behaviors: the tool creates/attaches to the user's team, links anonymous resources, returns a 24-hour session token (not to the agent), and requires subsequent authentication via 'get_api_token'. It also clarifies what the upgrade_jwt is not (per-resource UUID). While rate limits or idempotency are not mentioned, the description covers the most important behavioral aspects.

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 concise and well-structured. It front-loads the main purpose, then provides essential details about the flow, constraints, and alternatives. Every sentence adds value; there is no redundancy or fluff.

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 has 2 parameters and no output schema, the description provides complete context: it explains the input parameters, the process (team creation, resource linking), the output (session token, but not returned to agent), and follow-up actions ('get_api_token' or dashboard). It also covers error handling implicitly by mentioning the alternative tool when email 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 the schema already describes both parameters. However, the description adds value by explaining the source of 'upgrade_jwt' (from create_* tool responses or the 't=' query param) and clarifying 'email' leads to team creation/matching. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: 'Convert an anonymous upgrade JWT into a claimed team programmatically (POST /claim).' It specifies the endpoint, the input (JWT), and the outcome. It also distinguishes itself from the sibling tool 'claim_resource' by mentioning an alternative when the user's email is unavailable.

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 explicit guidance: use this tool when you have the user's email; otherwise use 'claim_resource'. It also explains the source of the upgrade_jwt (from create_* tools or upgrade URL) and what to do with the session token afterwards (use 'get_api_token' or dashboard). This is a clear when-to-use and when-not-to-use instruction.

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

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

With no annotations provided, the description fully carries the burden by disclosing behavioral traits: returns a redis:// URL, multi-tenant safety, anonymous tier limits (5 MB, 24h TTL), paid tier sizes, auto-expiry vs manual deletion, and env semantics.

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 appropriately sized with clear paragraphs, front-loaded with the main action, and every sentence adds meaningful information without 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?

Despite no output schema, the description covers return value, tier details, cleanup behavior, and environment scoping, making it fully complete for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the env choices and the name format with an example, going beyond the schema's descriptions.

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

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

The description clearly states 'Provision a fresh Redis cache on instanode.dev (POST /cache/new).' It uses a specific verb ('Provision') and resource ('Redis cache'), distinguishing it from sibling tools like create_postgres or create_nosql.

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 clear context on when to use the tool (e.g., anonymous vs paid tiers, env scoping) but does not explicitly compare it to alternative tools or state when not to use it.

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

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

The description fully compensates for the lack of annotations by detailing key behaviors: asynchronous build with polling, tarball construction and size limits, resource binding token semantics, env var merging, private deploy coupling and client-side validation, plan requirements, and authentication. No contradictions are present.

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 very long and detailed, which is necessary given the tool's complexity, but it lacks conciseness. It is front-loaded with the essential purpose but includes substantial explanatory sections. Some redundancy exists (e.g., tarball cap mentioned twice). It is well-structured but could be trimmed without losing value.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is nearly complete. It covers async behavior, tarball construction, plan requirements, private deploy details, env var and resource binding merge, coupling, client-side validations, and auth. It lacks explicit mention of the output schema (e.g., exact fields returned), but it notes the deploy_id and status for polling.

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

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

Although schema coverage is 100%, the description adds substantial value beyond the schema. It explains the redeploy parameter's use case, the coupling of private and allowed_ips, the resource_bindings token-based approach, tarball_base64 construction instructions, env parameter scope and default, and provides examples for clarity.

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

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

The description clearly states the tool's main action: 'Create a new deploy — OR set redeploy: true to update an existing deployment.' It specifies the resource (deploy) and the action (create/update), and distinguishes from the separate redeploy sibling by noting that using the same name with redeploy:true preserves the URL, avoiding the trap of duplicate deployments.

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 explicit guidance on when to use the tool (e.g., deploying CRM, internal dashboards) and when to use redeploy:true (shipping v2). It also mentions plan requirements (Hobby+ for deploys, Pro+ for private deploys) and when the tool fails (HTTP 402 for anonymous/free). However, it does not explicitly compare to the sibling redeploy tool, so the score is slightly reduced.

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?

Discloses that no token is needed for anonymous calls, but with a valid bearer token links to the caller's team. Returns UUID on success. No annotations are provided, so the description carries the full burden; while it covers key behaviors, it omits potential errors or side effects, which prevents a perfect score.

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?

Well-structured and concise: first sentence defines action, then usage context, then parameter guidance, then auth behavior, then return value. Every sentence adds value without 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?

Given no annotations or output schema, the description is comprehensive: covers purpose, usage, parameters, auth, and output. It explains the endpoint, required field, optional benefit, and linking behavior, making it complete for a form-submission tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that providing 'company' and 'use_case' gives context for an accurate quote, which is advice beyond the schema.

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

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

Clearly states it submits an enterprise contact/interest form to instanode.dev (POST /api/v1/leads). Distinguishes itself from sibling resource-creation tools by focusing on enterprise inquiries.

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 specifies when to use: when the user needs enterprise-tier features like dedicated infrastructure, SAML/SSO, SOC 2, or custom SLA. Also notes it's faster than a cold email, providing clear 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?

With no annotations, the description fully discloses all behavioral traits: connection URL format, user role scoping, tier limits, TTL auto-expiry, note/upgrade fields, and the absence of on-demand delete for anonymous tokens.

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?

Well-structured with main purpose first, but slightly verbose; all sentences are informative.

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 all essential aspects (return values, auth, tiers, cleanup, env) despite no output schema, making it fully self-contained.

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

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

Schema coverage is 100%, and the description adds context beyond schema: default env, response echo, and name examples.

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

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

Clearly states the action ('Provision a fresh MongoDB database') and the resource ('on instanode.dev'), distinguishing it from siblings like create_postgres or create_vector.

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 tier-based usage guidance (anonymous vs paid) and cleanup options, but does not explicitly compare to sibling tools for 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?

No annotations are provided, so the description fully carries the burden. It discloses anonymous tier limits (10 MB, 2 connections, 24h expiry, 5/day per /24 subnet) and paid tier behavior. It explains cleanup mechanics and warns that there is no on-demand delete for anonymous tokens. It also advises storing the URL as an environment variable.

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 well-structured and informative, with clear sections for functionality, connection URL, tier limits, and cleanup. It is slightly verbose but every sentence adds value. Front-loaded with the core action.

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 absence of annotations and output schema, the description covers all essential aspects: provisioning action, parameter requirements, tier-specific limits, cleanup behavior, and usage instructions. It is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning for parameters: it emphasizes 'name' is required and a human label, but doesn't elaborate on 'env' beyond schema. It doesn't add format or constraints not already in the schema.

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

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

The description clearly states it provisions a Postgres database on instanode.dev, specifies pgvector is pre-installed, and returns a standard connection URL. It distinguishes from sibling tools like 'create_vector' or 'create_nosql' by focusing on Postgres.

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 explains when to use this tool (provisioning Postgres) and provides tier-specific guidance (anonymous vs paid). It mentions cleanup behavior (auto-expiry for anonymous, delete_resource for paid), but doesn't explicitly exclude scenarios or suggest alternatives for other database types.

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

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

Given no annotations, the description covers key behaviors: returns a nats:// URL with scoped user, JetStream enabled, cleanup auto-expiry for anonymous, on-demand delete for paid, and auth token requirements. It omits rate limits or error scenarios but is fairly comprehensive.

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 paragraph that efficiently conveys purpose, usage, tiers, cleanup, and requirements. It is not overly verbose, but could be slightly more structured with bullet points for readability.

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 description explains the return format, auth requirements, tier differences, and cleanup policies. It lacks an example output or mention of error responses, but given no output schema, it covers the essential context well.

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?

Input schema coverage is 100% with clear descriptions for both parameters. The tool description adds no further semantic information beyond what the schema provides, justifying a baseline score of 3.

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

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

The description explicitly states it provisions a NATS JetStream queue on instanode.dev, distinguishing it from other resource creation tools like create_postgres or create_cache. The verb 'Provision' and resource 'NATS JetStream queue' are specific.

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 indicates when to use the tool (durable streams, pub/sub, work queues) and differentiates between anonymous and paid tiers with TTL and quota details. However, it does not explicitly state when not to use it or compare to other queue-like siblings.

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

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

With no annotations provided, the description must fully disclose behavior. It does so comprehensively: asynchronous build, polling via get_stack, status states (building/healthy), timeouts (6h anonymous TTL), rate limiting by subnet, and detailed response fields. There is no contradiction.

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 verbose but well-structured with clear sections and front-loaded purpose. Every sentence adds value given the tool's complexity. Could be slightly more concise, but it earns its length.

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

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

Despite lacking an output schema, the description thoroughly explains all return fields and the asynchronous lifecycle. The complex tool is well-documented: example manifest, dependency resolution, anonymous vs. authenticated behavior, and polling instructions. No 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 description coverage is 100%, so baseline is 3. The description adds significant extra semantics: explains the multipart shape, async nature, manifest examples, per-service tarball caps (50 MiB each, 200 MB total), and environment scoping. This goes well beyond the schema's descriptions.

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

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

The description clearly states 'Deploy a multi-service bundle from a single MCP call' and explains the key value proposition: one tool call yields a live URL. It distinguishes from siblings like create_deploy (single service) and other resource tools. The purpose is specific and actionable.

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 explains when to use this tool (multi-service bundle with dependencies) and provides context about anonymous vs. token usage, TTL, and rate limiting. While it doesn't explicitly say 'don't use for single service', the sibling tools and the description's focus on multi-service make it clear. It lacks explicit alternatives but is adequate.

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

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

With no annotations, the description fully discloses behavioral traits: anonymous tier auto-deletes after 24h, no on-demand delete for anonymous, paid tier permanent and deletable via delete_resource. It also explains cleanup mechanism and that the response carries note/upgrade fields. This is comprehensive.

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 well-structured: first sentence states purpose, followed by technical details, tier differences, cleanup, and a note on required field. It is efficient but could be slightly trimmed. Nevertheless, it earns its length by providing essential 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?

Given the absence of output schema and annotations, the description covers all necessary context: purpose, usage scenarios, parameter behavior, tier differences, cleanup, and response fields. It is complete for a tool of this complexity.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds no new semantic value beyond the schema—e.g., it reiterates that 'name' is required and that 'env' defaults to development, both stated in schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool provisions an S3-compatible object storage bucket prefix with a specific verb 'Provision' and resource, and mentions the API endpoint. It distinguishes itself from siblings (e.g., create_postgres, create_vector) by specifying it's for storage, backed by DigitalOcean Spaces.

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 explains when to use anonymous vs paid tiers, the 24-hour TTL, and that delete_resource can be used on paid tiers. It provides clear context on authentication (INSTANODE_TOKEN) and lifecycle behavior. However, it does not explicitly compare with other create_* tools, but the purpose is distinct.

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

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

With no annotations, the description fully discloses behavior: underlying storage is Postgres with pgvector preloaded, dimensions are a hint, authentication tiers with limits, and return type (connection URL). It also notes functional equivalence with create_postgres, setting accurate expectations.

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

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

The description is well-structured and front-loaded with the main action. However, it is somewhat verbose with detailed tier explanations. It earns its sentences but could be slightly more concise.

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 no output schema, the description adequately covers outputs (connection URL, anonymous tier response fields). It explains all three parameters and their semantics. Slightly lacking in full response structure, but sufficient for a creation tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining the dimensions default (1536) and that it's a hint, and clarifies the env parameter's default and purpose. This pushes the score to 4.

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

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

The description clearly states the tool provisions a pgvector-enabled Postgres database on instanode.dev, specifying the HTTP endpoint and use case for embedding stores. It distinguishes itself from the sibling create_postgres by noting functional equivalence and intent-based 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?

Explicitly tells when to use this tool vs create_postgres: to make intent explicit for pgvector/embeddings. Also details anonymous vs token tiers with specific limits, guiding the agent on appropriate authentication 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?

With no annotations, description carries full burden and excels: details returned receive_url, HTTP method handling, storage mechanics, cleanup policies (auto-expire for anonymous, on-demand delete for paid), and response fields ('note', 'upgrade'). Discloses behavioral traits comprehensively.

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?

Well-structured with front-loaded purpose, followed by behavior, use cases, tier details, and cleanup. Every paragraph adds value, though slightly verbose. Efficient for the complexity covered.

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 no output schema, description covers creation, usage, and lifecycle well. Explains return value (receive_url) and response fields. Lacks exact response format, but otherwise complete for a creation tool with tiered behavior.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minor context (e.g., env defaults to 'development', name is required) but largely reiterates schema info. Does not significantly extend meaning beyond the schema.

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

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

Description clearly states the tool provisions an inbound webhook receiver URL on instanode.dev, specifying the endpoint and behavior. It distinguishes itself from sibling tools (none are webhook-related) with a specific verb-resource combination.

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 explicit use cases (testing Stripe/GitHub/Slack webhooks, inspecting payloads, building integrations) and differentiates tiers with token vs. anonymous. Does not explicitly compare to alternatives, though the unique nature of webhooks makes this less necessary.

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?

No annotations exist, so the description fully discloses effects: stops container, releases compute, removes URL, irreversible deletion. Also specifies token requirement. This is comprehensive for a mutation tool.

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

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

The description is concise with two meaningful sentences and a token requirement line. Slightly informal phrasing but efficient; could be structured more formally.

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 tool (one parameter, no output schema), the description covers what happens and prerequisites. However, it omits mention of return value or error states, which might be useful.

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 input schema already provides a clear description and pattern for the single parameter 'id'. The description adds value by pointing out it comes from create_deploy's 'deploy_id', enhancing context beyond schema.

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

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

The description clearly states the tool tears down a running deployment with specific actions (stops container, releases compute, removes public URL, marks deleted). It distinguishes from siblings like 'delete_resource' by focusing on deployment resources.

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 (to delete a deployment) and warns it's irreversible, but does not explicitly contrast with alternatives like pause_resource or wake_deployment, leaving the agent to infer 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?

With no annotations provided, the description carries the full burden. It discloses that deletion is permanent, drops underlying databases/ACLs/storage, and marks row status='deleted'. It also details the tier restrictions and auto-expiry behavior. However, it omits error scenarios or response details, which would enhance transparency further.

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 relatively long but well-structured, with clear sections explaining the operation, tier restrictions, and cleanup details. While it could be trimmed slightly, the length is justified by the complexity of the platform's behavior. The information is front-loaded with the core action.

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 simplicity (one parameter, no output schema), the description covers the core action, prerequisites, and platform-specific behavior. It explains what happens to the underlying resources and the tier distinction. It lacks details on the response format or error handling, which would complete the picture.

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 input schema has 100% coverage with a description for the 'token' parameter. The description adds minimal extra meaning beyond the schema, noting that it is a path parameter. This is adequate but does not significantly enhance understanding beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: permanently delete a resource. It specifies the verb 'delete', the resource type, and distinguishes from sibling tools like pause_resource by emphasizing permanence. The HTTP method and path are also provided, leaving no ambiguity.

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

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

The description provides explicit guidance on when to use (paid tier resources) and when not to (anonymous/free tiers auto-expire). It explains the alternative for anonymous tiers (do nothing) and outlines the prerequisite (claiming resources first for paid tiers). It also mentions the required INSTANODE_TOKEN.

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

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

With no annotations provided, the description fully discloses critical behaviors: the one-step trust chain restriction (PATs cannot mint PATs), revocation-based lifetime, and return format. It also mentions the 403 error scenario, ensuring agent understands limitations.

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 detailed and well-structured, front-loading purpose and then explaining the crucial limitation and flow. While every sentence is informative, it is slightly lengthy; a more concise version could achieve the same clarity.

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 has one optional parameter, no output schema, and no annotations, the description covers all necessary context: behavior, error handling, usage flow, and return format. It is fully adequate for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100% with the 'name' parameter already described in the input schema (pattern, maxLength, example). The tool description does not add additional semantics beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool mints an API key and returns it as plain text. While it distinguishes the limited use case (dashboard session token only) and contrasts with dashboard manual minting, it does not explicitly differentiate from sibling tools like 'claim_token'.

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 explicit when-to-use (dashboard session token) and when-not-to-use (PAT cannot mint PAT, user should use dashboard for rotation). It also gives a step-by-step supported flow and directs to the dashboard as an alternative.

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

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

With no annotations, the description fully discloses behavior: the API iterates live plans registry so response is always current, lists all tiers and their properties, notes that exact numbers come from API (no drift), specifies no token required, and states response is identical for every caller.

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 relatively long but well-structured: front-loads purpose, then usage guidance, then details output fields. Every sentence adds value, though it could be slightly more concise without losing clarity.

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 zero parameters, no output schema, the description is very complete. It comprehensively explains the output structure (all fields) and behavior, compensating for lack of output schema. Also clarifies authentication and usage context.

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

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

The tool has zero parameters and schema coverage is 100% (trivially). Baseline is 4 per instructions; no additional parameter info needed. The description does not add parameter semantics because there are none.

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

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

The description clearly states it reads the live per-tier capability matrix with the endpoint GET /api/v1/capabilities. It specifies the 'get' verb and the resource 'capability matrix', and distinguishes from sibling tools like provision/deploy by advising to use this before those calls.

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

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

Explicitly states when to use: 'BEFORE a provision/deploy call to plan around tier limits instead of provisioning-to-discover them and eating a 402 mid-flow.' Also clarifies that no authentication token is required, making it accessible to cold-start agents.

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?

No annotations are provided, so the description bears full responsibility. It discloses it's a GET request, requires INSTANODE_TOKEN, and returns same shape as list_deployments. But it omits details like error handling (e.g., 404 if id not found) or idempotency, leaving some behavioral gaps.

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 concise sentences that front-load the main action, followed by usage context and requirements. No wasted words; every sentence adds value.

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

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

For a simple GET endpoint, the description covers the polling workflow, return shape, and authentication. Given no output schema and one parameter, it is sufficiently complete for correct agent usage.

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 input schema covers the single 'id' parameter 100% with pattern and description. The description adds valuable context by linking 'id' to the 'deploy_id' from create_deploy, enhancing meaning beyond the schema.

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

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

The description explicitly states the verb 'Fetch' and the resource 'one deployment by its app id', and clearly distinguishes itself from siblings like list_deployments (multiple) and create_deploy (creation).

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 explicit guidance to use this after create_deploy for polling until running status, which is clear context. However, it does not explicitly mention scenarios where it should not be used or alternatives for other needs.

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

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

With no annotations provided, the description fully discloses behavioral traits: it lists the exact fields returned (kind, reason, exit_code, etc.), confirms newest-first ordering, describes authentication (INSTANODE_TOKEN), and explains error handling (clean 'not found' for other teams). No annotations are present to contradict.

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 well-structured with bullet points and clear paragraphs. It is fairly long but every sentence adds necessary information. A minor cut could be the analogy 'the rule-27 self-correction surface,' which is evocative but adds little concrete value.

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

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

Despite no output schema, the description meticulously explains the return value (seven fields with examples), ordering, pagination behavior, and edge cases (empty list for successful deploys, 'not found' for unauthorized ids). No additional documentation is needed for effective use.

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

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

Schema coverage is 100% (both 'id' and 'limit' have descriptions). The description adds value by explaining that 'id' corresponds to 'deploy_id' from create_deploy or 'app_id' from get_deployment, and that 'limit' defaults to 50 if omitted. This goes beyond the schema, justifying a score above the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Read the failure-timeline autopsy for a deployment.' It specifies the verb (read), resource (deployment events), and distinguishes itself from the sibling tool 'get_deployment' by highlighting that it returns the full chronological autopsy versus just the latest error string.

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 explains when to use the tool: when a deploy is stuck in 'building' or flips to 'failed.' It also clarifies that a successful deploy may result in an empty list. However, it does not explicitly state when not to use it or list alternative tools, though the context implies its niche use case.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool uses the public route, does not require auth for anonymous callers, returns the same shape as create_stack, and lists response fields. However, it does not mention potential errors or rate limits, which would be needed for a perfect score.

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 approximately 120 words, well-structured with clear paragraphs. Every sentence adds value, and the main purpose is front-loaded. No unnecessary 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?

Given there is no output schema, the description thoroughly explains the return shape (same as create_stack with specific fields). It also covers auth requirements and polling context. For a single-parameter tool, this is complete and informative.

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

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

Schema coverage is 100%, and the description adds value beyond the schema: it describes the stack_id format ('stk-<8-char-hex>') and notes that it is returned by create_stack. This reduces ambiguity beyond the schema's description.

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

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

Clearly states 'Fetch a stack by id' and distinguishes from sibling tools by specifying polling after create_stack and contrasting with a dashboard-only route that requires auth. Verb+resource and usage context are 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?

Provides explicit guidance: 'Use this after create_stack to poll until every service is healthy (~30s typical).' Also explains when to use this public route versus the dashboard route based on auth requirements, giving clear 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?

Discloses returned fields (app_id, tier, status, etc.) and authentication requirement. No annotations provided, so description carries burden. Lacks information on pagination, sorting, or rate limits.

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

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

Three concise sentences. Front-loaded with purpose and endpoint. No redundant 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?

Given no output schema, description adequately explains return fields. However, lacks information on pagination or limits, which would be expected for a list tool.

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

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

No parameters in schema; baseline 4. Description adds value by enumerating return fields, which aids understanding.

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?

Clearly states verb 'list', resource 'deployments', and scope 'on the caller's team'. Distinguishes from sibling 'list_resources' and 'get_deployment'.

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

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

No explicit when-to-use or when-not-to-use guidance. No mention of alternatives or preconditions beyond requiring token.

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?

No annotations are provided, so the description must cover behavioral traits. It discloses that results are sorted newest first, scoped to the caller's account, and lists the returned fields. It does not mention pagination or rate limits, but for a simple list operation, this is adequate.

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 three short sentences, front-loaded with the purpose, and contains no superfluous information. Every sentence adds value.

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

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

Given no output schema and no parameters, the description provides sufficient context about the action, prerequisites, and return fields. It could mention pagination or maximum results, but it is otherwise complete for a straightforward list tool.

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

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

There are zero parameters, so the baseline is 4. The description does not need to explain parameters and correctly omits any reference to them.

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?

Description begins with 'List resources on the caller's instanode.dev account, newest first', clearly identifying the verb and resource. It distinguishes from sibling create/delete tools by focusing on listing and includes the HTTP endpoint.

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

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

States a clear prerequisite (INSTANODE_TOKEN) and provides a link to obtain one. While it doesn't explicitly contrast with sibling tools, the use case for listing vs. creating/deleting is self-evident.

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

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

With no annotations, description fully discloses behavioral traits: no data loss, stops new connections, revokes credential, preserves storage and URL. Also covers error conditions (409 for already paused, 402 for insufficient tier, 404 for invalid token) and authentication requirements (INSTANODE_TOKEN, Pro tier).

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?

Description is efficiently structured with the primary action first, followed by key details and use cases. No redundant sentences, though the authentication note could be placed earlier.

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?

While comprehensive, the description omits whether existing connections are terminated gracefully or left hanging. It also doesn't discuss return value or success indicators. Without an output schema, these details would help.

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 baseline is 3. Description adds value by explaining that the 'id' parameter is a resource token from a create_* call, which aids in understanding where to obtain the value.

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?

Description clearly states the action ('Suspend'), the object ('resource'), and explicitly distinguishes it from deletion. It specifies that storage and URL are preserved, making the purpose 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?

Provides concrete use cases (parking database, freezing during incident, temporary access cut) and directs to resume_resource for undoing. While it doesn't explicitly state when not to use, the context and sibling comparison (delete_resource) imply the appropriate scenarios.

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?

No annotations exist, so the description carries full burden. It fully discloses: expiration ≤1h (default 10 min), auth via token in path, scoped to tenant prefix, key restrictions (relative, no leading slash or '..'), and that DELETE is intentionally excluded to avoid data loss. This is comprehensive for a security-sensitive 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?

The description is well-structured: starts with a concise summary, then provides details on usage, auth, and constraints. Every sentence adds value—no filler. It is appropriately sized for the tool's complexity (4 parameters, security concerns).

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?

Despite no output schema, the description mentions the returned 'url' and how to use it. It covers all essential aspects: token source, operation restrictions, key format, expiration, and security rationale. The tool is moderately complex, but the description leaves no ambiguity about usage or behavior.

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

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

Schema description coverage is 100%, but the description adds significant value beyond the schema: it explains that the token comes from create_storage, gives context for the operation enum (including why DELETE is missing), and describes the expiration default and cap. This extra context helps the agent use parameters correctly.

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

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

The description clearly states the tool's purpose: mint a short-lived presigned S3 URL for upload (PUT), download (GET), or inspect (HEAD). It distinguishes itself from sibling tools by being the only presign tool, and explicitly ties to the storage resource created by create_storage.

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 explicit guidance on when to use (upload/download/inspect without long-lived credentials) and when not (DELETE not offered). Also explains that it works for anonymous-tier storage without INSTANODE_TOKEN, and gives concrete HTTP client usage examples. No alternative tools mentioned, but siblings don't overlap in purpose.

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?

No annotations exist, so description fully handles transparency. It discloses that a fresh tarball is required (no server-side reuse), flips status to 'building', and requires INSTANODE_TOKEN. Also corrects a previous erroneous claim about tarball reuse.

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?

Eight sentences, well-structured with a clear front-loaded purpose, usage guidance, and important behavioral notes. Slightly verbose due to the correction about a previous wrong description, but still efficient.

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

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

No output schema exists, but description covers the async rebuild process (polling, status changes), prerequisites (token), and tarball requirements. Lacks description of return values or error cases, but sufficient for an update tool.

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

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

Schema coverage is 100%, but description adds meaningful context: id is the deploy_id from create_deploy, and tarball_base64 shares the same shape as create_deploy.tarball_base64. Mentions size limits and contents.

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?

Clearly states the tool pushes updated code to an existing deployment by app id, and contrasts with create_deploy's redeploy option. The verb 'redeploy' and resource 'deployment' are well-specified.

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 tells the agent to use this tool when the deploy_id is known and a code change is needed without changing URL/app_id. Also recommends the alternative create_deploy with redeploy:true for name-based workflows.

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

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

With no annotations, the description covers key behavioral traits: flips status, re-grants credential, preserves connection URL, requires INSTANODE_TOKEN, and returns 409/404 on error. It omits details like rate limits or idempotency, but is sufficient for safe invocation.

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 concise (4-5 lines) and front-loaded with the core action. It uses a clear structure with details on behavior, limitations, and errors. Minor improvement could be using bullet points for readability.

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 description fully covers purpose, usage, behavioral implications, authentication, error handling, and prerequisite (Pro tier). No output schema is needed, and the given level of detail is complete for a simple resume operation.

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

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

Schema coverage is 100% with a clear description for the id parameter ('the value create_* returned as token'). The description adds no additional parameter-level insights, meeting the baseline for full schema coverage.

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

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

The description clearly states 'Un-pause a previously-paused resource' with a specific verb and resource. It explains the effect (flips to active, re-grants credential) and implicitly distinguishes from siblings like pause_resource by mentioning symmetry and the 409 error on non-paused resources.

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 explicit context: 'Pro tier or higher only', 'symmetric with pause_resource', and error conditions for misuse (409 if not paused, 404 for wrong token). It does not explicitly list alternatives to non-paused resources, but the sibling context is clear enough.

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?

No annotations exist, so the description fully carries the burden. It discloses that only credentials rotate (host/database unchanged), returns new URL in plaintext, requires INSTANODE_TOKEN, and returns 404 for unauthorized tokens. This provides good behavioral insight.

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 concise yet comprehensive, with a clear structure: action, behavior, usage, security note, auth requirement. Every sentence adds value, and it is front-loaded with the key purpose.

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 one parameter and no output schema, the description covers all essential aspects: what it does, when to use it, the nature of the response (plaintext URL), security handling, and authentication. It is complete.

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

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

Schema coverage is 100%, and the schema already describes the 'id' parameter as the resource token UUID. The description reinforces this but does not add new semantic detail beyond what the schema provides, meeting the baseline.

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

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

The description clearly states the verb 'Rotate' and the resource 'password', and specifies the outcome 'get the NEW connection URL'. It effectively distinguishes this tool from siblings like create_* or delete_resource by focusing on credential rotation.

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

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

Explicit usage scenarios are provided: after a suspected leak, on a key-rotation schedule, before handing off. No explicit 'when not to use' is given, but the context effectively implies it, and no alternative tools are mentioned, though the action is unique.

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

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

With no annotations, the description fully discloses that the tool mints a new version under a distinct audit action, that the running container keeps the old value until redeploy, and that the value is encrypted and not echoed. Also notes auth requirement.

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

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

Every sentence adds value. The description is front-loaded with the core purpose, followed by functional distinction, usage guidance, redeploy note, and auth requirement. No wasted words.

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

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

The description covers purpose, usage, side effects, and auth. However, it does not mention the return value or response format, which is a minor gap for a write operation. Still, given the thoroughness elsewhere and no output schema, a 4 is reasonable.

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

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

Schema coverage is 100% with descriptive parameter docs (env, key, value). The description adds no new parameter details beyond the schema, but the schema itself is sufficient; baseline 3 is appropriate.

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

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

The description clearly states the action ('Rotate a vault secret's value'), specifies the HTTP endpoint, and distinguishes the tool from its sibling set_vault_key by identifying the intended use case (compromised or expiring secret).

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

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

Explicitly states when to use this tool vs set_vault_key ('Use this when... use set_vault_key for...'), advises redeploying dependent apps, and mentions the required INSTANODE_TOKEN.

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?

No annotations provided, so description carries full burden. It discloses version creation, that plaintext is never echoed, authentication requirement (INSTANODE_TOKEN), and possible error codes (403, 402, 403 vault_env_not_allowed).

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 well-structured with a clear opening sentence followed by relevant details. It is slightly verbose but every sentence adds value.

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

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

Covers return value (version), error scenarios, and authentication. Without an output schema, it provides sufficient context for a simple write 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 has 100% coverage, but description adds critical context: env tier restrictions, key reference format, and value encryption/echo behavior. This goes beyond the schema's basic descriptions.

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

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

The description clearly states it writes a secret to the team vault using a specific HTTP method and path. It distinguishes itself from sibling tools like rotate_vault_key by focusing on writing/updating secrets.

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?

Explains when to use the tool: to populate a vault:// reference for create_deploy. Also covers tier restrictions and possible HTTP errors, but does not explicitly mention alternative tools for read 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?

No annotations provided, but description fully discloses key behaviors: merge semantics (not replace), secret redaction in response, redeploy requirement, vault support, auth token need, and 404 behavior for unauthorized access.

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?

Each sentence adds value; the description is front-loaded with primary action, followed by merge details, redeploy, vault, auth, and error handling. Concise yet comprehensive.

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 all key aspects: merge operation, response format, redeploy necessity, vault integration, auth, and error behavior. No output schema needed; description handles completeness.

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 100% of parameters, but description adds essential context: id source from create_deploy/get_deployment, env values can be plaintext or vault references, and merge behavior beyond 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?

Clearly states it merges environment variables into an existing deployment, with explicit verb and resource. Distinguishes itself from siblings like update_stack_env and set_vault_key.

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 explicit when-to-use (merge env vars), mentions redeploy requirement, suggests using create_deploy or redeploy to apply changes, explains vault references prerequisite, and notes authentication and error behavior.

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?

No annotations provided, so description bears full burden. Discloses transactionally row-locked concurrency, empty-string deletion semantics, redacted response, auth requirements, 404 for unauthorized slugs, and required token.

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?

Well-structured with clear first sentence followed by bullet-like paragraphs. All information is relevant and no unnecessary 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?

Covers all essential aspects: behavior, concurrency, deletion, response, auth, edge cases, and required subsequent action. No output schema but description suffices.

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?

Both parameters have detailed explanations beyond schema: env includes value types and deletion behavior, stack_id includes format and source. Schema coverage is 100%, but description adds significant value.

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?

Clearly states 'Merge environment variables into an existing stack' with HTTP method and path. Distinguishes from sibling update_deploy_env by noting 'same merge semantics but for a multi-service stack'.

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?

Specifies use case (multi-service stack), mentions alternative (update_deploy_env) implicitly, and explains required redeploy step. Lacks explicit when-not-to-use but context is clear.

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

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

With no annotations, the description fully discloses behavior: it scales to 1 replica and refreshes activity stamp, notes cold-start delay, explains the flag-gated 501 error, requires INSTANODE_TOKEN, and mentions 404 for unauthorized ids. No contradictions.

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 well-structured and front-loaded with the main purpose. It is slightly verbose but every sentence adds necessary context. Could be trimmed slightly without losing value, hence 4.

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

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

The description covers preconditions, behavior, and errors well, but fails to describe the successful response format or body. Since there is no output schema, the agent is left guessing what a successful wake returns. This gap lowers completeness.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema: it ties the 'id' to the URL path and mentions its origin from other tools. This is helpful but not a significant addition.

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 explicitly states the action: 'Explicitly wake a scaled-to-zero deployment' and ties it to the HTTP endpoint. It clearly distinguishes from sibling tools like pause_resource or resume_resource by focusing on the specific scenario of waking a deployment that was scaled to zero.

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 explicit guidance: when to use (when app returns 502/503 due to scale-to-zero), when not to use (when feature is disabled, deployment is always-on), and what to expect (cold-start time, need to retry). It also warns about 404 for non-owned ids.

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