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

With no annotations, the description covers key behaviors: approval, role assignment, request completion, validation, and permission requirements. It does not detail side effects or error scenarios, but for a straightforward approval tool 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?

Two sentences efficiently convey all necessary information: the action, effects, validation, and permissions. No redundant or extraneous 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 tool with 2 parameters and no output schema, the description covers the purpose, parameters, and prerequisites. It lacks return value details but is otherwise complete enough for an agent to use 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?

The description adds value beyond the schema by stating the default role and linking request_id to appcrane_list_access_requests. The schema already describes request_id, but the description clarifies its source and the role's effect.

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 approves pending access requests, grants access at a specified role, and marks the request as done. It distinguishes itself from sibling tools like deny_access_request and list_access_requests.

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 mentions verification that the request is an access request and enumerates required roles (app-admin, owner, global admin). While it does not explicitly state when not to use or list alternatives, the context is sufficient for basic 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?

Beyond the lack of annotations, the description explicitly discloses read-only nature, root restrictions, file size refusal, and a truncation workaround, providing comprehensive behavioral transparency.

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

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

The description is extremely concise, with two sentences that efficiently convey purpose and key constraints, front-loading the main 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?

Despite no output schema, the description covers constraints and behavior adequately for a file-reading tool. It could mention return format, but it's implied as file content.

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 description adds no new information about parameters beyond what the input schema already provides (e.g., path must start with /app or /data), but schema coverage is 67%, 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?

The description clearly states the verb 'Print' and the resource 'contents of a file inside a running app container', distinguishing it from sibling tools like appcrane_cp (copy) and appcrane_ls (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?

The description provides usage context: read-only, restricted to safe roots, and file size limit, with a suggested workaround for large files. It does not explicitly mention when not to use or alternatives like appcrane_cp.

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 fully bears the burden. It discloses multiple behavioral traits: single hop, no container/GitHub round-trip, no inline size ceiling; exact file path mapping; return of SHA-256 and byte count; assurance that secrets are never returned; and path constraints.

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 front-loads the core purpose and quickly adds crucial context. Every sentence provides value, though it is slightly verbose with some redundancy (e.g., path constraints repeated).

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 5 parameters, no output schema, and no annotations, the description covers purpose, usage, behavior, parameter hints, return value, auth, and safety. No major gaps remain; it is fully adequate for an AI agent to select 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% (all 5 parameters described in schema). The description adds some context (e.g., 'single hop') but largely reinforces schema details like path rules and encoding. Value added is marginal 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 action ('Copy/upload a file') and the target resource ('persistent /data volume on the host'). It distinguishes itself from siblings (e.g., appcrane_push_to_managed_app) by highlighting the lack of size ceiling and direct transfer, and lists aliases.

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: 'Right tool for multi-MB datasets, large fixtures, or anything where appcrane_push_to_managed_app's tool-arg ceiling would force chunking.' Also specifies prerequisites: 'App-admin or owner of the app required.'

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

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

Given no annotations, the description carries full burden. It discloses side effects: allocates ports, creates directories, configures routing, starts health checks. However, it omits details on failure behavior or idempotency.

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 concise (4 sentences) with critical info front-loaded: purpose, usage condition, actions, follow-up steps. 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?

Covers preconditions, actions, permissions, and next steps. For a 9-parameter tool with no output schema, it lacks return value description, but overall sufficiently complete for an agent.

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 high (89%), so baseline is 3. The description does not add additional parameter meaning 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 verb ('Register a new app') and resource ('AppCrane from a GitHub repository'). It distinguishes itself from sibling tools like appcrane_create_managed_app and appcrane_deploy by specifying the exact onboarding step.

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 ('only after the user has explicitly confirmed...') and provides a clear sequence of required follow-up calls (appcrane_set_secret, then appcrane_deploy). Also mentions the required permission level.

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 comprehensively discloses behavior: creates repo on org/user, platform ownership, agent workflow, return shape, and idempotent recovery with { repaired: true }. 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?

Well-structured with main purpose, usage, return info, and recovery details. Every sentence adds value, though 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 7 parameters with full schema, no output schema, and no annotations, the description covers key behaviors, usage, and recovery. Missing explicit return format but reasonably 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 covers all 7 parameters with descriptions. The description adds no additional parameter-level information beyond what the schema already provides. 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?

Clearly states it creates a new app using a GitHub service-account, distinguishes from appcrane_create_app by specifying the service-account approach and additional repo metadata, and includes idempotent recovery details.

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: when user does not have a GitHub account or wants to avoid GitHub. Also provides prerequisite (admin-configured service-account) and recovery guidelines for half-failed creates.

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 that the action marks request as done without granting access, optionally appends a reason to the original message affecting audit trail, and lists required admin roles. However, it does not mention irreversibility or potential notifications.

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: first states action and result, second explains optional reason effect, third notes permissions. Concise, front-loaded, 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?

No output schema, but description explains the behavioral outcome: marks request as done without granting, optionally appends reason. Sufficient for a denial action, though could mention any return values or confirmations.

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 50% (only 'reason' has description). The description adds meaning: 'Optionally appends a reason to the original message so the requester (and the audit trail) sees why.' This clarifies the parameter's effect. The 'request_id' parameter is implied to be the pending request's ID, though not explicitly 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?

The description clearly states the verb 'Deny' and resource 'pending access request'. It specifies that it marks the enhancement_request as done WITHOUT granting access, distinguishing it from sibling tools like appcrane_approve_access_request and appcrane_set_request_status.

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

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

The description says 'Deny a pending access request' and mentions required roles ('App-admin / owner / global admin required'). It implies usage context but does not explicitly contrast with sibling tools like appcrane_approve_access_request.

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 explains the internal process (pulls latest commit, builds Docker image, swaps container) and return value (deployment ID). Could mention reversibility or failure handling, but overall 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?

Description is well-structured with a key action upfront, followed by details. Every sentence adds value, though slightly verbose. No wasted words, but could be slightly tighter.

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 explains return value and monitoring. Covers the process and parameter behavior. Sufficient for a two-parameter tool with moderate 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%, but description adds context: slug is the app identifier, stage defaults to sandbox and production requires confirmation. This goes beyond schema details, adding usage 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?

The description clearly states it triggers a deployment to update an environment to the latest, with specific verb and resource. It distinguishes from sibling tools like rollback or logs by focusing on 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?

Explicitly lists use cases ('update sandbox to the latest', 'deploy the newest version') and mentions alternatives (use appcrane_get_logs to monitor). Also notes default stage is sandbox and production requires user confirmation.

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 describes the return content and error behavior (404-equivalent). For a read-only tool, this is adequate transparency.

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

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

Two sentences: first covers purpose, second covers usage and error. Every sentence is valuable and front-loaded. 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?

Despite no output schema, the description fully explains the return content (URLs, versions, deployments, health) and error case. Complete for a simple retrieval 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% with a well-described slug parameter. The description adds no new parameter meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly states it retrieves detailed info for a single app, listing specific data types (URLs, versions, deployments, health). It distinguishes from siblings like appcrane_list_apps or appcrane_get_health by focusing on a single app's comprehensive status.

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

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

Explicitly tells when to use the tool (e.g., ask about status, after deploy) and mentions error cases. Does not explicitly exclude alternatives, but the specificity is sufficient.

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 discloses the scope (pre-container output) and the nature of errors covered. However, it does not mention response format (text/plain) or potential limitations like log truncation, but this is partially covered by the 'tail' parameter.

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

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

Single well-structured paragraph. Front-loaded with purpose, then usage context, then parameter alternatives. 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?

Covers the core purpose, distinguishes from siblings, explains parameter options, and provides use-case guidance. Missing details on error handling (e.g., if both deployment_id and slug+env provided) but overall complete for the tool's complexity.

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

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

Schema already covers 100% of parameters with descriptions, but the tool's description adds significant context: clarifies the relationship between deployment_id vs slug+env, explains the default for 'tail' (500), and states that stage is required when deployment_id is omitted. This goes beyond schema 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 reads deploy/build logs from pre-runtime stages (clone, npm install, docker build, health-validate), distinguishing it from sibling appcrane_get_logs which shows runtime logs. The verb 'Read' and resource 'deploy/build log' are specific and unambiguous.

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

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

Explicitly states when to use this tool (fast deploy failures) versus alternatives (appcrane_get_logs for runtime), and how to specify the deployment via deployment_id or slug+env. Also references prerequisites (deployment_id from other 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?

No annotations provided, but the description discloses that it returns markdown, defaults topic to 'onboarding', and details what each topic contains. For a read-only fetch, it adequately covers behavioral traits.

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 dense with information but remains clear and front-loaded. It could be slightly more structured, but every sentence earns its place without excess.

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 and no annotations, the description provides thorough context: what it does, when to use it, topic details, default behavior, and return format. It is complete for a simple fetch tool.

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

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

The schema covers 100% of the parameter with enum and description. The description adds further meaning for each enum value, clearly explaining what 'onboarding', 'operations', and 'email' contain, going beyond the basic 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 fetches the latest AppCrane playbook on a given topic, using a specific verb and resource. It distinguishes itself from sibling tools that perform actions on apps, making its 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?

Explicitly advises using it at the start of non-trivial workflows to get authoritative guidance, providing clear context. It does not explicitly mention when not to use it, but the context and sibling tools make alternatives understood.

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 were provided, so the description alone must convey behavioral traits. It explains that the tool bypasses the auth proxy, hits the configured health endpoint directly on the internal port, and returns response status and body. This provides useful insight into the tool's mechanics. However, it does not describe error handling (e.g., what happens if the app is down or the endpoint is missing), which would improve transparency.

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

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

The description is a single, well-structured paragraph with no wasted words. The first sentence states the core function, the second provides use cases, the third explains internal behavior, and the fourth gives parameter guidance. Every sentence serves a purpose, and the layout is easy to parse.

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 health-check tool with two parameters and no output schema, the description covers the essential aspects: purpose, use cases, internal behavior, and parameter default. It mentions the return includes status and body. However, it lacks information about possible errors or failure modes, which would enhance completeness for an agent.

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

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

The schema already describes both parameters fully (slug with example, stage with enum and default). The description adds value for the stage parameter by clarifying when to use 'production' vs 'sandbox'. However, no additional semantics are provided for slug. Given 100% schema coverage, the baseline is 3, and the added context for stage is sufficient to maintain that score.

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 that the tool fetches the health endpoint server-side, bypassing the auth proxy. It identifies two specific use cases: validating a deploy and checking if the app is responding. While it doesn't explicitly differentiate from sibling tools, the purpose is concrete and not a tautology.

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 contexts for using the tool: 'to validate that a deploy actually landed the expected version, or to check if the app is responding.' It also gives a specific guideline for the stage parameter: 'Defaults to sandbox; pass stage="production" only when the user asks about prod.' No explicit exclusions or alternatives are mentioned, but the guidance 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?

No annotations provided, but the description explains the tool returns the most recent N lines (default 100, max 1000), supports case-insensitive substring filtering via search, and notes error case ('no such container' errors occur pre-container). It implies read-only behavior but could be more explicit about idempotency.

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 concise paragraphs. First paragraph states purpose and key parameter details. Second paragraph clarifies exclusion with a concrete example. No filler, front-loaded with 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 4 parameters, no output schema, and no annotations, the description covers all critical aspects: function, parameters (with defaults and limits), filtering, stage, and importantly when not to use with a sibling reference. Agent can correctly invoke it.

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

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

Schema coverage is 50%. Description adds meaning for 'lines' (default, max) and 'search' (case-insensitive substring filter), and mentions 'stage' implicitly. However, the required 'slug' parameter is not explained, relying on context from the tool name. Overall partial compensation for missing schema 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 opens with 'Get recent runtime logs from a running app container (docker logs)', using a specific verb and resource. It distinguishes itself from sibling tool appcrane_get_deploy_log by clarifying this is for runtime issues, not deploy failures.

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 'NOT the right tool for fast deploy failures... Use appcrane_get_deploy_log for that.' Provides clear when-to-use (runtime issues), when-not-to-use (deploy failures), and a named 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?

Discloses that secrets are returned decrypted, defaults to sandbox, requires app-admin/AppCrane admin role, and non-admins get permission error. No annotations provided, but description fully covers 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?

Three sentences, front-loaded with main action, no fluff. Efficient and well-structured.

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 could specify the return format (e.g., list of key-value pairs). Otherwise covers behavior, role, and error cases 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?

Schema coverage is 100%, so the schema already documents both parameters adequately. The description adds context about stage default but doesn't significantly expand parameter meaning beyond schema 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 retrieves all secrets (encrypted environment variables) decrypted for an app. It distinguishes from siblings like appcrane_set_secret (modifies) and appcrane_get_app (different resource).

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 when to use: when user asks about config/secrets or verifying env vars. Provides guidance on default stage and explicitly warns against using production unless user specifies. Also mentions required roles and permission errors.

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 idempotent behavior, user input flexibility (id/email/username, first match wins), role default, and permissions, though it omits the response format.

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, no redundant 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?

Covers purpose, input flexibility, idempotency, and permissions; missing success response details, but acceptable without output schema.

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

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

The description adds meaning for the 'user' parameter (accepts id/email/username, first match wins) beyond the schema's brief description, and confirms the default for 'role', compensating for the 33% 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 explicitly states the tool grants user access to an app at a specific per-app role, using a specific verb and resource, and distinguishes from siblings like revoke_app_access.

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

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

It mentions required permissions (app-admin or owner) and idempotency, but does not explicitly list alternatives or when-not-to-use, though context with siblings makes it 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 discloses the data source, filtering pattern, and scope behavior. It is a read-only operation, but does not mention potential side effects or performance, which is acceptable for a list tool.

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

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

Two sentences with no wasted words. Purpose is front-loaded and all essential information is conveyed compactly.

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 and no output schema, the description explains the filtering and permissions adequately. Missing description of return format, but completeness is high for a simple listing tool.

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

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

Schema coverage is 100% for the single parameter. The description adds value by explaining the scoping behavior (returns across all apps if omitted) beyond the schema's 'Limit to one app'.

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 lists pending access requests, identifies the specific database source (enhancement_requests rows starting with 'Access request for app'), and distinguishes itself from sibling tools like approve/deny by focusing on listing.

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 clear guidance on when to use with slug (scope to one app) vs without (all adminable apps), and states required permissions. Does not explicitly mention alternatives but context implies this is for viewing, not modifying.

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 covers the return format and required permissions. It implies a read operation but does not explicitly state it is read-only, which would be a minor improvement.

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 two sentences, front-loaded with purpose and output, then usage guidance and permissions. No fluff, 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 tool with one parameter and no output schema, the description covers all necessary aspects: purpose, output fields, usage context, and permissions. 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?

The only parameter 'slug' has no schema description, and the description does not elaborate on its format or source. However, the context makes it clear it identifies the app, so it is adequate but not fully compensatory for the 0% 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 the tool lists users with their roles, specifying the verb 'list', the resource 'app members', and the output details (email, name, role). It also distinguishes from sibling tools like grant and revoke by recommending use before those operations.

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 advises 'Use this before granting or revoking to see who is already in.' Also states required permissions: 'App-admin or owner of the app required (or global admin / platform_admin).'

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 the description carries the burden. It discloses role-based visibility (non-admin vs admin) and the included fields. This is transparent for a read-only list 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?

The description is concise with three sentences, each providing essential information: action, return fields, usage guidance, and access control. 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?

The description covers the purpose, return fields, and role-based behavior. It lacks mention of pagination or error handling, but for a simple list with no parameters, it is sufficiently 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?

There are no parameters and schema coverage is 100%. The description adds no parameter info, which is acceptable as per baseline 4 for zero 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 clearly states it lists apps the user has access to, including specific fields (slug, name, description, urls, versions). It distinguishes from siblings (the only list tool for apps).

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 explicitly advises to call this first when asking about 'my apps' or before app-specific operations. It also explains visibility differences based on role, providing good context for when 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?

No annotations provided, so description carries the burden. It discloses the timing constraint (after most recent deploy) and output contents. Does not explicitly state read-only nature, but the verb 'list' implies it. Role requirement mentioned. Could be more explicit about permissions.

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: first covers purpose and output, second covers usage and role. Front-loaded, 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?

No output schema, but description explains return fields. Covers source, timing, and target users. Could mention potential pagination or limits, but overall sufficient for typical 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 description coverage is 50% (stage has description, slug does not). Description implies slug identifies the app but adds no new details for slug. For stage, it replicates the schema info ('omit to list both envs'). Description does not fully compensate for missing schema 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?

Description clearly states the tool lists scheduled jobs from an app's deployhub.json cron array, with specific fields included. It is distinct from sibling tools like appcrane_run_cron_now.

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 for verifying registration, debugging missing runs, or reading logs. Identifies target users as app-admin or owner. Lacks explicit alternatives or 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?

No annotations provided, so description is the sole source. It discloses that results are newest first and includes return fields, but lacks details on error handling, pagination, or whether the operation is read-only. The description adequately implies a safe, read-only operation.

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

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

Two sentences that front-load the core purpose and return fields, then give usage guidance. Every sentence earns its place with 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?

Given no output schema, the description adequately covers the return fields and purpose. It mentions limit/ordering indirectly via 'newest first' but does not describe pagination or error scenarios. For a list tool with clear parameter defaults, this is reasonably 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 67%, below the 80% threshold for baseline 3. The description adds meaning by stating 'for an app + env' (mapping to slug and stage), but does not detail slug format or the limit parameter's effect. This provides moderate added value over 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 the tool lists deploy/release history for an app+env, newest first, with specific fields. It distinguishes itself from siblings by mentioning its use for picking a target for appcrane_rollback.

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 explicitly says 'Use this to see what is live and to pick a target for appcrane_rollback' and notes 'App access required,' providing clear context for when to use it. It does not explicitly state when not to use it, but the guidance is sufficient.

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 bears the burden of disclosing behavior. It explains return fields (id, message, app_slug, submitter, bucket), bucket meanings, and that omitting slug shows all accessible apps. It lacks details on ordering or pagination but covers essential 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?

The description is concise with three sentences: one for purpose and use cases, one for return fields, and one for bucket explanations and a tip. No extraneous information; every sentence 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?

Given no output schema and 3 parameters, the description covers purpose, usage context, return fields, bucket definitions, and a filtering tip. It omits sorting and error handling but is sufficient for an agent to select and invoke the tool correctly in most scenarios.

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 67% (slug and bucket described, limit not). The description adds value by reiterating the bucket filter tip and confirming slug omission behavior, but does not elaborate on the limit parameter beyond what the schema provides (default, min, max). 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 explicitly states the tool lists enhancement requests from the AppCrane intake form and provides concrete use cases like 'what should I work on?' and 'what's queued for X?'. It clearly distinguishes from sibling listing tools (e.g., list_apps, list_releases) by focusing on requests with bucket categorization.

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 tells when to use the tool (user asks about work items, picking up tickets) and suggests filtering by bucket='triage' to find unclaimed work. It doesn't explicitly mention when not to use alternatives, but the sibling context and specific bucket guidance provide adequate direction.

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

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

No annotations are provided, so the description fully discloses behavior: it is read-only, bound to safe roots (/app and /data only), and returns the directory listing as text. This is comprehensive for a simple listing 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 three sentences long, with the first sentence front-loading the purpose. Every sentence adds value: purpose, use case, safety, and output format. No redundant or 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?

Given the tool's simplicity (list files), the description covers all essential aspects: what it does, when to use it, safety constraints, and output format. No output schema exists, but the description mentions the return type as text, which is sufficient. The description is complete for effective 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?

Schema coverage is 67% (path and stage have descriptions, slug does not). The description reinforces the path constraint (must start with /app or /data) but does not add much beyond what the schema already provides. For slug, no additional semantics are given, so the parameter description is not significantly enriched.

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 'List' and the resource 'files inside a running app container at a specific path'. It distinguishes this tool from sibling tools like appcrane_cat or appcrane_cp by focusing on listing directory contents. The purpose is unambiguous.

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

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

The description gives a specific use case: 'Use to verify what actually got built / what files made it into the deployed image.' It implies when to use this tool, though it does not explicitly mention when not to use it or provide direct comparison to siblings. The context of safe roots and read-only further guides appropriate usage.

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: refusal conditions, health-check with auto-revert, different behaviors for github vs managed/upload apps, and owner-only restriction. This provides excellent transparency.

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

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

The description is extremely concise, using three sentences with no fluff. It front-loads the main action and conditions, making it easy to scan.

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

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

Given the complexity of a promotion action with multiple preconditions and behaviors, the description is highly complete. It covers the gated path, health checks, auto-revert, and app type differences. No output schema exists, but the behavioral description compensates adequately.

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 only parameter 'slug' has no description in the schema (0% coverage), and the tool description does not explain what 'slug' refers to (e.g., app slug). The description should compensate for the low schema coverage but fails to add semantic meaning to the parameter.

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

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

The description clearly states the verb 'promote' and the specific resource 'current live SANDBOX release to production'. It distinguishes from siblings like appcrane_deploy and appcrane_rollback by specifying the sandbox→prod path and gating conditions.

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 (to promote sandbox to production) and provides clear conditions for refusal (sandbox not live or unhealthy, not owner). However, it does not explicitly name alternative tools for different scenarios, though the context makes the usage 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?

No annotations provided, so description carries full burden. It discloses path validation rules, that the container must be running, and that the staged blob is deleted on success. However, it lacks details on error handling or idempotency.

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?

Single paragraph but well-organized: starts with purpose, then usage context, then step-by-step process. Every sentence is informative 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?

No output schema, but description doesn't explain return value. It covers prerequisites, path constraints, and deletion behavior. Could mention success/failure indication, but otherwise complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds context beyond schema: for 'token' it explains source (returned by POST), for 'dest' it adds validation constraints. This adds value, raising from baseline 3.

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

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

The description explicitly states the verb 'Move' and resource 'previously-staged file into a running container at a path under /app or /data'. It distinguishes from sibling appcrane_cp by noting it's for large binaries too big to inline.

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?

Clearly states when to use: for large binaries when they're too big for appcrane_cp. Provides explicit two-step process prerequisites: uploading via POST and requiring the container to be running.

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 authentication, batch commit behavior, per-file integrity check, staged upload process, and version-specific changes, ensuring the agent understands operational 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?

Well-structured with front-loaded purpose, but includes detailed version notes and examples that make it verbose; still earns its length for a complex tool.

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

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

Covers authentication, file types, sizes, integrity, and staged upload; lacks formal return schema but describes response fields (sha256, bytes) and error handling ('fail loudly'). Almost 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?

Adds significant meaning beyond schema: explains slug resolves to AMC_<slug>, encoding behavior with staged_token, and detailed staged_token workflow. Schema coverage is 75% but description compensates fully.

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?

Explicitly states 'Push a batch of files to a managed app's AMC_<slug> repo' and contrasts with github_push_files, making the tool's purpose and intended use clear.

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

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

Provides explicit guidance: 'Use this — NOT github_push_files — for managed apps' with rationale, plus prerequisite 'Requires the app to already exist via appcrane_create_managed_app', and instructions for large files versus inline.

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 the full burden. It discloses idempotency, permission requirements, and the only-owner protection, which are critical behavioral traits beyond the schema.

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

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

Three concise sentences, front-loaded with the main action, and no wasted words. Efficiently covers key points.

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 tool, the description covers input, behavior, permissions, and edge cases. It lacks explicit output format, but the tool's simplicity makes this omission acceptable.

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 50% (only 'user' has a description). The description does not add explicit param details beyond the schema context, but the app context implies 'slug' is the app identifier. Adequate but not compensatory.

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 'Remove' and the resource 'user access from an app', distinguishing it from sibling tools like appcrane_grant_app_access.

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

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

The description provides explicit guidance on idempotency, required permissions (app-admin, owner, global admin), and a special case (refuses to remove the only remaining owner). It lacks explicit comparison to alternatives but 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 carries the full burden. It discloses that releases re-use cached images (no rebuild if retained), health-checks occur, a new deployment is recorded, and the previous one is marked rolled_back. Access restrictions are stated. Missing potential failure scenarios, but overall 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?

Three sentences: purpose, parameter behavior, and execution details. Each sentence adds unique value with no repetition. 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?

No output schema, so the description should explain return values or error conditions. It mentions health-checks but not failure handling or the response format. For a mutation tool with side effects, this is a gap, but the core behavior is well-covered.

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% (2 of 3 parameters described in schema). The description adds context: deployment_id is sourced from list_releases, the two rollback modes, and stage as legacy alias. It compensates for the undocumented slug parameter by implying its role as the environment identifier.

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

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

The description begins with a clear verb and resource ('Roll an env back'), specifies two modes (target specific release or roll back to previous), and distinguishes from sibling tools like appcrane_deploy or appcrane_promote by its unique rollback 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?

The description explains when to provide deployment_id vs omit it, references a source tool (appcrane_list_releases), and notes owner-only access. It does not explicitly exclude alternatives, but the usage is sufficiently clear for an agent.

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

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

Despite no annotations, the description thoroughly discloses behavior: idempotent (skips if already running), runs docker exec, updates metadata, and returns exit code and log. Authorization implied ('App-admin or owner').

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?

Fairly concise, front-loaded with main purpose, and efficiently covers use cases and behavior in a few sentences. Could be slightly shorter, but nearly ideal.

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

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

No output schema exists, but the description explains returns (exit code and log tail). Covers authorization, idempotency, and internal mechanism (docker exec). Complete for a single-action tool.

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

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

The description adds no information about input parameters beyond what the schema already provides. The schema has 67% coverage (two of three parameters described), and the slug parameter lacks a description in both schema and description.

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

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

The description clearly states the tool triggers a cron job immediately, with concrete use cases and a clear verb + resource. It distinguishes itself from sibling tools like appcrane_list_cron.

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 ('test daily rebuild without waiting', 'rerun yesterday's failed job'). Does not explicitly compare to alternatives, but the intended 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 carries the full burden. It discloses that the tool replaces any existing icon, requires app-admin or owner permissions, and mentions a 500 KB size limit. While it doesn't detail side effects or rollback options, the provided information is sufficient for safe usage.

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 sentences) and front-loaded with the main purpose. Every sentence contributes necessary context: usage guidelines, format options, alternative approach, and authorization requirements. No superfluous 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?

Given the lack of output schema and annotations, the description adequately covers purpose, usage, behavior, and parameters. It does not describe the return value (e.g., success/error), but for a setter tool this is acceptable. Overall, it provides a complete understanding for an agent to use 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?

The input schema covers all three parameters (slug, base64, format) with descriptions. The description adds practical value: it clarifies that base64 can include or omit the data URL prefix, specifies the max decoded size, and explains format determines the file extension. This enhances usability beyond the schema alone.

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: 'Set the tile icon for an app' and specifies where the icon appears. It distinguishes the tool from the alternative of committing a repo icon, making its 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?

The description explicitly explains when to use the tool ('when the icon needs to change without a redeploy, or when the source isn't in the repo') and when not to ('For repo-tracked icons prefer committing public/icon.png to the repo'). This provides clear usage guidance.

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

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

No annotations exist, so description carries full burden. It comprehensively discloses behaviors: owner/admin requirement, visibility enum values, auth_mode details (headless bypasses all forward_auth), auth_bypass_paths header stripping and logging suppression, domain DNS and TLS provisioning, and category constraints. No contradictions with missing annotations.

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

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

The description is front-loaded with purpose and includes structured parameter details. While verbose, it efficiently packs necessary information without redundancy. Could be slightly trimmed, but the complexity justifies 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?

Given 6 parameters, no output schema, and no annotations, the description covers all parameter details, ownership constraints, behavioral implications, and security considerations comprehensively. No obvious gaps for the intended functionality.

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 descriptions, but the description adds significant value beyond schema: explains headless mode use cases, auth_bypass_paths logging suppression and security context, domain requirements, and category ownership constraints. This enriches parameter 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?

The description clearly states the tool sets app's category, visibility, auth_mode, and auth_bypass_paths, distinguishing it from sibling appcrane_update_app for admin-only fields. Verb 'set' and specific resource details provide unambiguous 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?

Explicitly states required roles (owner or global admin), provides guidance on when to use headless mode (telemetry ingest, public webhooks, status pages) vs. auth_bypass_paths, and directs to alternative tool for powerful fields. This offers clear context for appropriate usage.

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 discloses that validated requests are considered closed and that the tool requires app-admin or AppCrane admin role. Since no annotations are provided, the description adequately covers behavioral traits for a simple state transition 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 extremely concise: two sentences that cover purpose, lifecycle, examples, and role requirement. No unnecessary words, 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 (2 required params, no output schema, no nested objects), the description is complete. It explains the lifecycle, provides usage examples, and specifies role requirements, which is sufficient for an agent to correctly invoke the 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 that id is the request # column and bucket is the target, which adds minimal meaning beyond what the schema already provides (enum values and 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 moves a request through a lifecycle with specific transitions (triage to in_progress to shipped to validated). It gives concrete examples of when each transition should be used, making the purpose very clear.

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

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

The description explicitly lists when to use each state transition (e.g., "I'll take #42" for in_progress, after merging PR for shipped, after confirming fix for validated). It does not explicitly mention when not to use this tool or alternatives, but the provided scenarios are sufficient for basic 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?

No annotations are provided, so the description carries full burden. It discloses encryption at rest, that only the running app can read plaintext, defaults to sandbox, and admin requirements. However, it does not mention whether setting a secret triggers any deployment or restart, nor does it discuss overwriting behavior or potential side effects.

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 four sentences, concise, and front-loaded with the purpose. 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?

The description covers encryption, permissions, stage default, and scope. It lacks details on value size limits or key validation, but for a simple write tool, it is fairly complete. No output schema exists, but the tool's return is not complex.

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% (3 of 4 parameters have descriptions; slug lacks description). The description adds context about encryption and stage defaults, but does not elaborate on each parameter beyond what the schema provides. Baseline 3 is appropriate given the 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 'Set or update a secret (an encrypted environment variable injected into the app).' It uses a specific verb (set or update) and resource (secret), and explains what a secret is, distinguishing it from sibling tools like appcrane_get_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?

The description provides guidance: 'Defaults to sandbox; require explicit stage="production" only when the user asks.' And 'App-admin or AppCrane admin only.' It also mentions scope respect. It does not explicitly state when not to use, but the 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?

The description discloses data source (app_visits, Caddy forward_auth), ordering (by user count descending), and access restriction (Admin only). This exceeds what structured fields provide, though it lacks details on edge cases like empty results.

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

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

Four sentences, each serving a distinct purpose: purpose, use cases, data source, ordering and access. No wasted words, front-loaded with key 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, the description covers return ordering and data source. It is adequate for a simple list tool but could mention error handling (e.g., non-admin access).

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 have clear descriptions. The description reinforces 'lookback window' and 'how many rows' but adds no new information beyond the schema, resulting in baseline score.

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: 'Top apps by distinct active users in a lookback window' and provides concrete example questions that differentiate it from siblings like appcrane_top_users.

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 includes example use cases ('which apps are getting the most use this week') but does not explicitly state when not to use the tool or name alternatives. However, the context is adequate for typical usage.

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 must carry full burden. It mentions data source ('app_visits') and access restrictions ('Admin only') but does not explicitly state that the tool is read-only or non-destructive. More transparency about safety would be beneficial.

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 key purpose, and every sentence adds value. No wasted words.

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

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

For a simple list tool, the description provides sufficient context: what it does, data source, use cases, and access. Lack of output schema means an agent must infer return structure, but the description's clarity compensates mostly.

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 clear descriptions for both parameters (top and days). The tool description adds no additional meaning beyond what the schema already provides, resulting in a baseline score.

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 'Top users by distinct apps opened in a lookback window' with a specific verb ('surfaces') and resource ('top users'). It distinguishes itself from sibling 'appcrane_top_apps' by focusing on users rather than apps.

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 use cases are provided ('finding power users to interview, or spotting churn risk') and context like 'Active users only' and 'Admin only' gives clear when-to-use guidance. However, it does not mention when not to use or alternatives.

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

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

With no annotations, the description carries full burden. It explains partial updates ('Only includes fields you pass; omitted fields are left alone'), how to clear a string field (empty string), and token encryption ('Stored encrypted (AES-256-GCM)'). It also indicates the return shape. Missing are side effects like triggering a redeploy 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?

Two tight sentences with front-loaded purpose. Every phrase adds value: the verb 'patch', immediate use cases, the scoping statement, clearing instructions, and return reference. 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 no output schema, referencing appcrane_get_app for return shape is appropriate. The description covers the core behavior (partial update, clearing fields). However, given the tool's complexity (16 params), it could explain interactions or constraints (e.g., required slug but not other required fields) but is adequate overall.

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 low (38%), so the description must compensate. It adds meaning for several parameters (github_url, token, branch, category, visibility, resource limits) but fails to cover many others (name, slug, domain, description, source_type, public_access, frame_ancestors, image_retention). The added value is moderate but incomplete.

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 identifies the tool as a patching operation for existing apps, listing specific use cases (fix github_url, change branch, rotate token, etc.) and distinguishing it from general app management by noting it handles 'anything you would otherwise need direct DB access for.' The verb 'patch' contrasts with other sibling tools like appcrane_create_app.

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 use cases are given ('fix a missing github_url... change branch... rotate the github_token...'), providing strong when-to-use guidance. However, it does not explicitly state when not to use or mention alternatives (e.g., appcrane_set_app_meta for metadata changes) or prerequisites, so it falls short of a 5.

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

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

No annotations, but the description thoroughly covers blocking behavior, terminal states, timeout (default 180s, max 600s), and return object on timeout. Transparent and 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?

Concise, well-structured, front-loaded with essential behavior. Every sentence adds value without verbosity.

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

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

Completes the picture for a blocking wait tool: explains return behavior, timeout handling, integration with appcrane_deploy, and no output schema needed because description covers return format. All relevant context included.

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 both parameters with descriptions (100% coverage). Description adds context that deployment_id comes from appcrane_deploy but doesn't substantially enhance semantic 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 clearly states the tool blocks until a deployment reaches a terminal state and returns final status. It distinguishes from siblings like appcrane_get_logs (polling) and appcrane_deploy (triggering).

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 after appcrane_deploy instead of polling appcrane_get_logs, describes immediate return if terminal, and explains timeout behavior. Full guidance provided.

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