reachpad-mcp

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

Beyond the annotations, the description discloses the key non-obvious behavior: Version 1 goes live at once, so there is immediate public exposure. It also states the default access behavior (org_link), which affects who can open the result. This adds meaningful safety-relevant context beyond the structured hints.

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 only three sentences and every sentence earns its place: the first states purpose and output, the second warns about immediate publication, and the third gives the access default. No filler or repetition of the schema.

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

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

The schema and annotations cover most operational details, while the description supplies the purpose, a live-on-publish warning, the default access, and the return value. It is nearly complete, though it does not explicitly route the agent away from update_app or publish_app_version for existing apps.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in detail. The top-level description adds general context about publishing and access defaults but does not add per-parameter meaning beyond what the schema provides. That matches the baseline for high 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 first sentence states a specific verb, resource, and output: 'Publish new files as an app and get its URL back.' It also signals that this is a new-app creation with 'Version 1 goes live at once,' which distinguishes it from version-update siblings like publish_app_version.

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 clear context and a practical precondition: 'show the person the content and the destination before calling this' because the version goes live immediately. It does not name alternatives explicitly, but its 'new files as an app' framing makes the create-versus-update use case reasonably 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?

Beyond the readOnly and idempotent hints, the description candidly discloses two important behavioral limitations: file-serving apps 'answers that it has no logs,' and function logs are not captured yet with the answer explicitly saying so. It also provides practical guidance to compensate, which is valuable behavioral context the annotations alone do not supply. No contradiction with annotations.

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

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

The first sentence front-loads the tool's core purpose, and the following sentences earn their place by explaining limitations and a workaround. There is a slight redundancy in saying the app 'answers that it has no logs' and later that 'the answer says so,' but overall it remains compact and useful.

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

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

For a simple read-only log tool, the description is complete: it defines what is returned, clarifies live-version scope, warns about unsupported app and function types, and explains the current logging gap. The schema already covers parameters and defaults, so nothing essential is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description adds general context like 'recent' but does not add parameter-specific meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Read recent log lines from the live version of a function app.' This clearly distinguishes it from file or version reading siblings such as read_app_file and read_app_version, and from management tools like update_app or share_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?

The description gives clear context about when the tool is useful and when it will not yield logs: file-serving apps have no process and no logs, and function logs are not yet captured. It also suggests a fallback workaround for functions. It does not explicitly name alternative sibling tools, so it stops short of a 5.

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

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

Annotations already signal readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds useful non-obvious behavior: it reports the roles attached and whether the grant has been claimed by an account, plus the owner-only authorization requirement. This exceeds what the annotations alone convey.

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

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

The description is two short sentences with no filler. The primary action comes first, the return content is summarized, and the authorization constraint is appended compactly. Every clause earns its place.

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

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

For a simple one-parameter, read-only list operation, the description provides the essential context: what is listed, what fields are included, and who may call it. There is no output schema, so the description's mention of people, roles, and grant attachment partially fills that gap, though a bit more return-format detail could make it fully self-sufficient.

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

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

Schema description coverage is 100% and the single app_id parameter is well documented in the schema, including its format and how to obtain it. The tool description does not need to add param detail and adds none, so the baseline of 3 is appropriate.

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

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

The description opens with a clear verb and resource: 'List the people an app is shared with,' and specifies the meaningful output dimensions: roles and whether the grant has attached. It is clearly distinct from sibling tools like share_app and revoke_app_share, which mutate sharing rather than read it.

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 clear usage context: this is the read-only listing operation for app shares, and it adds an explicit access constraint, 'Owner only.' However, it does not explicitly name alternatives such as share_app or revoke_app_share for modifying shares, so the when-not-to-use guidance is mostly implied by the verb.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond those annotations: versions are ordered newest first, are immutable, are numbered from 1, and pagination is cursor-based. This is meaningful, non-redundant information.

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 concise sentences with no filler. It front-loads the core purpose, then adds immutability and pagination details that are directly useful for calling the tool correctly. 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?

The tool is simple, the input schema fully documents all parameters, and the description explains ordering and pagination. There is no output schema, so a slightly richer statement about the response shape could improve completeness, but nothing an agent needs to invoke the tool correctly is missing.

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

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

The input schema has 100% parameter description coverage, so the baseline is 3. The description reinforces the meaning of the cursor parameter ('next_cursor from a previous call') but does not add significant extra semantics beyond what the schema already provides for app_id and limit.

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 ('List an app's versions') and the resource ('app versions'), and adds useful ordering information ('newest first'). It does not explicitly differentiate this from the sibling read_app_version tool, but the verb 'list' combined with the plural resource makes the purpose reasonably 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 concrete pagination guidance: 'Pass the next_cursor from a previous call to get the next page.' However, it does not explicitly say when to use this tool instead of alternatives like read_app_version or publish_app_version, leaving the selection logic largely implicit in the tool name.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: that only names and metadata are returned, not secret values, and that no other tool will expose secret values. This directly shapes agent expectations and prevents misuse.

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 clear sentences with no filler. The main purpose and output scope are front-loaded, and the security-relevant note about secret values is stated separately, making the definition easy to parse and remember.

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 list operation with no parameters and no output schema, the description fully covers what the agent needs to know: what it lists, what fields come back, and what it deliberately does not return. No critical behavioral or security context is missing.

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

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

The tool has zero parameters and an empty input schema, so there is nothing to document. The baseline for zero-parameter tools is 4, and the description does not need to compensate for any missing parameter information.

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

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

The description states a specific verb ('List'), a resource ('the organization's secrets'), and the exact output fields (name, setter, time, binding apps). It also distinguishes itself from sibling mutation tools by stating that no tool returns a secret value, making the tool's role unmistakable.

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 tool's use case is clear: enumerate organization secrets and their metadata. It does not explicitly name alternatives to avoid, but the statement 'No tool anywhere returns a secret value' gives practical guidance against seeking secret values elsewhere. For a zero-parameter listing tool, this is adequate context.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful behavioral detail beyond annotations: it returns direct children only, includes apps and subfolders, and notes that folders carry the updated_at field needed by mv.

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 zero fluff. The core purpose is front-loaded, the top-level usage note is immediate, and the mv dependency note earns its place by linking behavior to a sibling tool.

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

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

For a simple read-only listing tool without an output schema, the description adequately conveys what is returned, scope of results, and top-level behavior. It does not mention ordering or detailed item representation, but those are not critical for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description reinforces the folder_id omission rule but does not add meaningful semantic detail beyond the schema.

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

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

The description uses a specific verb and resource: list what is directly inside one folder, namely subfolders and apps. It clearly distinguishes this from recursive listing, especially since sibling 'tree' exists.

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 clear practical context: omit folder_id for the top level, and list only direct contents of one folder. It does not explicitly name alternatives or when-not-to-use cases, 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?

Annotations already indicate a mutating, non-destructive, non-idempotent operation; the description only restates 'create.' It adds no behavioral detail such as failure behavior, permissions, or whether existing folders are handled.

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

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

One short, front-loaded sentence with no filler. The key verb and resource appear first, and the optional nesting behavior is included efficiently.

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 creation tool with full schema coverage and safety-relevant annotations, the description is nearly complete. It lacks only explicit usage guidance and edge-case behavior, which are minor given the tool's simplicity.

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

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

Schema coverage is 100% and both parameters are documented ('folder name' and 'folder to create it inside'). The description's parenthetical essentially restates the parent_id schema description and adds no new meaning.

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

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

The description names the specific action (create), resource (folder), and scope (top-level or nested). This cleanly distinguishes it from rmdir for removal and ls/tree for 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?

It conveys that the tool is used for creating folders and that parent_id is optional, but it gives no explicit guidance on when to prefer mkdir over a sibling or when not to use it. No alternatives or exclusions are named.

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

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

Beyond the annotations, the description discloses the optimistic-concurrency guard: a stale base_updated_at causes the move to be 'refused instead of undoing someone else's.' This explains why a failure occurs and what it prevents, adding real behavioral value the annotations do not provide.

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 dense sentences with zero filler. The action and object are front-loaded, the one-of constraint follows immediately, and the concurrency rationale earns its place by explaining the otherwise surprising base_updated_at requirement.

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 4-parameter move tool with no output schema, the description covers the core semantics, the destination semantics including top-level moves, and the concurrency requirement. It could mention what a successful call returns, but the absence of an output schema makes this a minor gap rather than a blocker.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by reinforcing the mutual-exclusion rule ('Name exactly one of app_id or folder_id') and by explaining the purpose of base_updated_at — that it guards against stale reads. This goes beyond the schema's bare field 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 a specific verb and resource: 'Move an app into a folder, or move a folder under another folder.' This precisely distinguishes the tool from siblings like mkdir, rmdir, and ls, making its scope 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 clear operating context: 'Name exactly one of app_id or folder_id' and 'to_folder_id as the destination, or null for the top level.' It does not explicitly exclude sibling alternatives, but the calling pattern is so specific that an agent can infer 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?

Beyond the idempotentHint annotation, the description adds meaningful behavior: 'Nothing is rebuilt, the pointer moves.' This tells the agent the operation is a lightweight live-managing action rather than a build or deploy step, and clarifies the rollback effect. It doesn't cover auth or error cases, but those are not central here.

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

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

Three short sentences with no filler. The main action is front-loaded, the intended use cases follow, and the behavioral caveat is last. 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?

For a simple two-parameter tool with fully described parameters, the description and schema together give the agent enough to invoke it correctly: what it does, when to use it, and what effect it has. No output schema is present, but the effect ('pointer moves') is sufficient context for selection and invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that number is a version number via 'by its number' and 'name an older number,' but adds no new format, source, or units beyond what the schema already documents.

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 a specific verb and resource: 'Make one version of an app live by its number.' It clearly distinguishes this tool from siblings like list_app_versions, read_app_version, and update_app by framing it as the pointer-moving/live-switching operation.

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

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

It explicitly names two use cases: publishing a version staged with publish false, and rolling back by selecting an older version. It doesn't name sibling alternatives or exclusions, but the conditions for choosing this tool over read/list/update tools are still evident.

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

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

The description discloses important behavior beyond annotations: only one statement is allowed, a second is refused, schema-changing statements are refused, and return shapes differ for selects versus writes. This is substantial operational context that the annotations alone do not provide. No contradiction with the annotations is present.

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

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

The description is three dense sentences with no filler. It front-loads the core purpose, then states exclusions, permissions, and output behavior. Every sentence contributes to correct invocation.

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 having no output schema, the description explains what the tool returns for both select and write statements. It also covers the key constraints: one statement, no schema changes, and ownership requirements. For a tool of this complexity, nothing essential is missing.

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

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

Schema description coverage is 100%, and the schema already documents app_id, sql, and params, including placeholder usage and the single-statement rule. The description adds useful return-shape context but not much per-parameter meaning beyond what the schema supplies. The baseline of 3 is appropriate here.

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

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

The description states a specific action: run one SQL statement against the app's own database, for reading rows or fixing data. It also explicitly excludes schema changes and routes those to migrations, which distinguishes it clearly from any file or migration-related siblings.

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

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

It gives clear when-to-use guidance: read or fix data via SQL. It gives an explicit when-not-to-use and alternative: schema changes belong in a version's migrations file and are refused. It also states the permission boundary: owners and editors only.

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

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

Annotations already mark the tool read-only and idempotent, but the description adds substantial behavior: file content is included unless content_omitted/too large, and explains version, head_version, pending_version, and staging semantics. This is exactly the context that structured annotations cannot convey.

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

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

Every sentence earns its place: the first sentence front-loads the core purpose, then follow-ups explain file handling, update_app linkage, and version semantics. Although dense, it is appropriately sized for a tool with no output schema and meaningful version-state nuance.

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

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

With no output schema, the description carries the full burden of explaining return behavior, and it covers the essential app fields, version identifiers, staging state, and file-content edge cases. There is no sign of missing information an agent would need to call the tool correctly for its intended pre-update workflow.

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

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

The single parameter app_id is fully documented in the schema (100% coverage), so the description does not need to repeat it. The description adds no parameter-level meaning beyond the schema, which aligns with the baseline 3 for high 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 states a specific verb and resource ('Read one app') and immediately scopes it to the pre-update workflow, naming the fields returned (name, type, access level, publishing mode, version identifiers). It explicitly contrasts with read_app_file for large/omitted file content, so an agent can distinguish it from a close sibling.

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

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

It gives an explicit trigger ('before update_app'), says to pass base_version_id to update_app, and directs content_omitted/too large files to read_app_file. This is strong when-to-use guidance with alternatives.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds material operational constraints: the 256 KB text answer limit, refusal of non-text or oversized files rather than truncation, and the default-to-newest-version behavior tied to read_app's version listing.

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

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

Three dense sentences cover purpose, use cases, limits, refusal behavior, and versioning without padding. The most important information is front-loaded, and there is no repetition of schema details.

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

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

For a simple single-file read operation with read-only annotations, the description covers when to use it, input semantics, output size limits, failure behavior, and versioning. No output schema exists, but 'as text' and the explicit size cap are sufficient for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by specifying that the version number corresponds to the same version list read_app exposes and that the newest version is used by default, reinforcing the relationship between versions and the file path.

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

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

The description states a specific verb and resource: reading one file from an app as text. It also differentiates itself from read_app by noting it fetches a single file without the rest of the app, making its scope 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?

It explicitly gives two triggering conditions: use it when read_app marks a file as content_omitted/answer budget, or when only one file is needed. It indirectly identifies read_app as the alternative for whole-app reads, providing clear when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context beyond annotations by clarifying that the result includes the version's files and the contents of each text file.

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 compact sentences with no filler. The core action and scope are front-loaded, and the use-case guidance earns the second sentence.

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

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

For a simple two-required-parameter read operation with strong annotations, the description is complete: it states what is read, what is returned, and when to use it. No output schema exists, but the description sufficiently covers the relevant return shape.

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

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

Schema description coverage is 100%, so the schema already fully documents app_id and number. The description does not add new parameter-level meaning; it merely restates that the version is looked up by its number.

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

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

The description names a specific verb and resource: 'Read one version by its number,' and further specifies the return scope: 'with its files and each text file's content.' This clearly differentiates it from siblings like list_app_versions and read_app_file.

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 explicitly states when to use the tool: 'Use it to see what an earlier publish contained, and to copy a file back out of a version you want to return to.' It does not explicitly mention when not to use it or name alternative tools, so it stops short of a 5.

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

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

The description adds detail beyond the annotations by explaining that deletion propagates to published versions, that unreached versions remain in a failed state, and that re-running retries exactly those versions. This aligns with destructiveHint=true and idempotentHint=true without contradicting them.

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 filler. The primary action is front-loaded and the second sentence conveys the failure/retry behavior efficiently.

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

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

For a one-parameter destructive operation, the description covers scope, failure behavior, and retry semantics, while annotations cover read-only/destructive/idempotence. No critical calling detail is missing despite the lack of an 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?

Schema description coverage is 100% and the only parameter is already documented as 'The secret name, from list_secrets.' The description does not add extra parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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

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

The description names a specific action ('Remove one organization secret') and resource, and clarifies the scope ('delete it from every published version that binds it'). This clearly differentiates it from sibling tools like set_secret and list_secrets.

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

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

The opening clause states exactly when to use the tool. It does not explicitly name alternatives or exclusions, but the operation is unambiguous and the failure/retry guidance gives useful context for using it correctly.

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

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

Annotations already declare destructive, non-read-only, and idempotent behavior. The description adds useful context beyond those annotations by stating that the app itself remains untouched and that ownership is required, which meaningfully clarifies the blast radius and authorization of the operation.

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

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

Three short sentences, each carrying essential information: what is removed, where the ID comes from, non-destructive scope relative to the app, and the ownership constraint. There is no filler or redundancy.

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

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

Given a simple two-parameter operation, no output schema, and annotations that already cover destructive and idempotent traits, the description provides enough context: single-share scope, ID source, app unaffected, and owner-only restriction. Minor details such as exact error behavior or irreversibility are not stated, but they are not essential for this tool's simplicity.

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

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

Schema coverage is 100%, so both parameters are already documented with their prefixes and meanings. The description adds marginal value by indicating that share_id comes from list_app_shares and that exactly one share is removed, but it does not significantly expand on 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 states a specific verb ('Remove'), the exact resource ('one share by its id'), and the source operation ('from list_app_shares'). It also clarifies scope ('The app itself is untouched') and a permission constraint ('Owner only'), making it easy to distinguish from sibling tools like share_app and list_app_shares.

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 clear context for use: revoking a single share by ID, with an owner-only precondition. However, it does not explicitly discuss when not to use this tool or compare it with alternatives such as share_app or list_app_shares, so the guidance is implied rather than explicit.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true, readOnlyHint=false), the description adds critical behavioral detail: it refuses while the folder contains apps or subfolders, and it never deletes an app. This explains the real-world effects and constraints of the operation without contradicting the annotations.

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

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

Three short sentences: the core action, the refusal conditions, and the required prerequisite. Every sentence adds necessary information, and the most important usage rule is front-loaded.

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

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

For a single-parameter destructive tool with annotations already carrying safety hints, the description covers what the tool does, when it fails, and what the agent should do first. Nothing important is missing.

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

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

Schema description coverage is 100%: the only parameter, folder_id, is described as 'The folder to delete.' The description adds no additional parameter-level detail, but none is needed for such a simple schema. Baseline 3 applies.

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

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

The description clearly states a specific verb and resource: 'Delete an empty folder.' It also distinguishes itself from sibling tools by explaining that it refuses to delete folders containing apps or subfolders and never deletes an app, which separates it from tools like trash_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?

The description gives clear when-to-use guidance: only for empty folders. It also tells the agent what to do before calling it ('Move the contents out first') and states the failure condition when the folder is not empty. It does not explicitly name sibling alternatives like mv, but the guidance is strong 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?

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses important search behavior: matching is substring-based rather than meaning-based, and it returns ids and live URLs. This helps the agent set expectations about output and query formulation.

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 with no filler. Each sentence earns its place: the first states the purpose, the second explains a non-obvious matching behavior and the return value. This is efficiently front-loaded.

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

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

The description is largely complete for a read-only search tool: it covers scope, matching behavior, and return content. Minor gaps include not explicitly addressing behavior when q is omitted and not describing how filters interact with the text search, though the schema supplies most of that detail.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the q parameter's semantics more precisely: it matches substrings of name and slug, and users should search for words appearing in the title rather than describing meaning. Other parameters are not enriched, but the schema covers them.

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

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

The description states a specific verb and resource: 'Find apps in the caller's organization by text.' It also clarifies the matching scope ('substrings of the name and the slug'), which distinguishes this search tool from read/list operations among the siblings.

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

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

It gives clear usage guidance: search for a literal word that appears in the title or slug, not a semantic description. It also scopes the operation to the caller's organization. It does not explicitly name alternative tools or exclusion cases, so it stops short of a 5.

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

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

Annotations already declare the mutation and idempotency profile, so the bar is lower. The description adds value beyond annotations by disclosing the owner-only authorization requirement and the behavioral constraint that passwords/expiries apply solely to public links. It doesn't contradict any annotation, though transition effects on existing shares aren't disclosed.

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

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

Three sentences, about 50 words, with the core purpose front-loaded and every sentence earning its place: purpose with level definitions, parameter scoping, and authorization constraint. No filler or redundancy.

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

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

For a moderate-complexity tool with 6 parameters and no output schema, the description covers the essential decision points: level semantics, parameter applicability, and owner-only restriction. Minor gaps remain around what happens to existing passwords/expiries when changing levels, but nothing critical is missing for correct invocation.

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

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

Schema coverage is 83%, which sets a baseline of 3. The description adds meaning beyond the schema by defining each enum value for 'level' and clarifying that password/expires_at only apply to public_link, compensating for the one schema field (level) that lacks its own 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 uses a specific verb ('Change') with a precise resource ('who can open an app') and enumerates all three access levels with their exact meanings. This makes the tool's operation unambiguous and implicitly distinct from siblings like share_app or update_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?

The description provides clear context: password and expiry parameters are scoped to public_link only, and the operation is restricted to the owner. This gives explicit exclusions for parameter usage and a stated authorization precondition, though it doesn't name alternative tools for distinguishable cases.

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 important behaviors beyond the annotations: setting an existing name replaces the value and rotates it onto every published version that binds it, and the response includes the name, count of updated versions, and ids of any that failed. This complements the idempotentHint and destructiveHint annotations without contradiction.

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

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

The description is two sentences with no waste. It front-loads the core action, then adds permission scope, overwrite/rotation behavior, and the response shape. Every sentence contributes useful information.

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

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

For a two-parameter tool with full schema coverage and relevant annotations, the description is complete. It covers purpose, permission, overwrite consequences, rotation semantics, and return value shape. No critical gap remains for an agent to call it 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 already provides 100% coverage for both parameters, including detailed semantics for value. The description adds the organizational context and the manifest-binding purpose, but it doesn't need to explain parameter syntax since the schema does. This meets the baseline for full schema coverage.

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

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

The description opens with a specific verb and resource: 'Set one organization secret' and immediately explains the purpose ('so a function can bind it by name in its manifest secrets list'). It clearly differentiates from sibling tools like list_secrets and remove_secret by focusing on creation/update of a single named 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 usage context is explicit: use this when you need to set a secret that functions can bind by name. It also states that any organization member can call it. It doesn't explicitly mention alternatives like list_secrets or remove_secret, but the 'set one secret' framing and sibling names make the appropriate use case 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 adds valuable behavior beyond annotations: it discloses the pending-grant behavior for addresses without an account and the owner-only restriction. This complements the readOnlyHint=false annotation without contradicting it.

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

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

Three short sentences each carry distinct information: the core action, the edge-case behavior, and the ownership restriction. No filler or redundancy.

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

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

For a simple share action, the description covers the essential behavioral details and parameter semantics through the schema. It does not describe the return value, but this is unlikely to be critical for a tool that returns no structured output.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds little beyond restating the viewer/editor roles, which are already in the role enum.

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

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

The description states a precise action ('Give one email address access to an app') with the exact resource and the access levels ('viewer or editor'). It clearly differentiates from siblings like revoke_app_share and list_app_shares.

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

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

The description implies when to use it by naming the action and includes an important restriction ('Owner only'), but it does not explicitly compare to alternatives such as set_app_access or explain when not to use it.

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

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

Annotations declare destructiveHint and idempotentHint, but the description adds essential behavioral nuance: the action is not permanent, the app and versions are retained, restoration is possible, and only the owner can perform it. This gives the agent a precise mental model of consequences beyond the raw hints.

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, all informative, with the main action front-loaded. Every sentence earns its place: immediate effect, permission, retention/restoration, and where permanent deletion occurs. No 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?

For a single-parameter mutation tool with no output schema, the description covers the key behavioral aspects: effect, timing, permission, data retention, restoration path, and the boundary between trash and permanent deletion. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents app_id. The description does not add any parameter-specific meaning beyond what the schema states, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Move an app to the trash.' It distinguishes this from permanent deletion by explaining that the app and its versions are kept and restorable, which differentiates it from any possible delete/move siblings.

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

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

The description gives clear context: the link stops opening at once, owner-only restriction applies, and restoration is possible from a specific Trash location. It implicitly tells the agent when to use this tool (non-destructive removal) and when not to (permanent deletion), though it does not explicitly name an alternative tool.

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

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

Annotations already cover the safety profile (read-only, idempotent, non-destructive). The description adds genuine behavioral context beyond those annotations: the result is nested, per-folder app counts are included, a top-level count is present, and each node exposes `updated_at` for `mv`. No contradiction with annotations.

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

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

The entire description is one dense sentence with no filler: it states scope, nesting behavior, the counts, and the `updated_at` detail. It is front-loaded with the most important fact (the whole folder tree) and every clause adds information.

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

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

For a parameterless read-only tool with no output schema, the description covers the key return semantics: full tree, nested structure, counts, top-level count, and per-node `updated_at`. It does not specify exact response field names or types, but those details are less critical given the tool's simplicity and annotation coverage.

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

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

The tool has zero parameters, so there is nothing for the description to clarify about inputs. The baseline for a zero-parameter tool is 4, and the description appropriately focuses on the return value rather than 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 identifies a specific resource ('the whole folder tree for the organization') and the deliverable shape ('nested, with number of apps ... and updated_at'). It is clear, though it relies on the title and context to convey the read action and does not explicitly distinguish itself from sibling `ls`.

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

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

Usage is implied: an agent can infer this is for retrieving the full tree when it needs the complete organization structure, especially before `mv` since nodes carry the `updated_at` mv needs. However, there is no explicit when-to-use/when-not-to-use guidance or naming of alternatives such as `ls` for a narrower view.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden. It discloses that base version conflicts are refused, default replace deletes omitted files (destructive), merge builds on prior merges including staged versions, env is readable by anyone, secrets must already exist, and validate writes nothing. It also surfaces that a manifest replaces the whole manifest, requiring all needed fields to be resent.

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 but every sentence earns its place, covering the base version requirement, default behavior, merge semantics, staging, validation, and manifest replacement. It front-loads the most critical operational constraint (read first, pass base_version_id). The schema's parameter descriptions are verbose but they are structured content, not description bloat.

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

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

For a 9-parameter mutation with nested objects, no output schema, and no behavioral annotations, the description manages to cover the critical workflow, destructive edge cases, merge semantics, the manifest replacement rule, secrets and env constraints, and the validate/staging paths. The only remote reference is a link to the full SKILL.md, which is acceptable because the description already summarizes 'the data plane in full, with its limits' and the link is supplementary.

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 every parameter, and the description doesn't repeat field-by-field details. However, the description adds cross-parameter semantics: base_version_id must come from read_app, remove only works with merge, an empty files array is valid for removals, and mode replace vs merge changes the meaning of files. That is valuable, but the schema already carries most parameter meaning, so a 3 is the right baseline.

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

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

Opens with a specific verb and resource — 'Publish a new version of an existing app' — and immediately distinguishes it from create_app by saying it's for an existing app. The description also names publish_app_version as the sibling that makes a staged version live, so an agent can tell this tool apart from related ones.

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

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

Gives explicit when-to-use and how-to-use guidance: read the app first and pass the base_version_id read_app returns, use merge only for changed files, use validate true to check without publishing, and use publish false to stage for later with publish_app_version. It also explains when not to use replace (whole file set, anything left out is gone) and flags review-before-publish behavior.

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

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

Annotations already mark the operation as read-only and idempotent, and the description adds meaningful behavioral context: it reports account identity, organizational memberships, and marks the current organization. It also discloses that apps are created only in the current organization and that the connection follows org switching, which is important non-obvious behavior beyond the annotations.

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

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

The description is front-loaded with the core purpose and return values, then adds a precise usage warning and switching context. It is somewhat dense and run-on, but every sentence carries useful information and the structure is logical.

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 zero-argument, read-only identity tool, the description is complete: it explains what is returned, that no arguments are needed, and why an agent should call it before publishing. The absence of an output schema is compensated by a clear explanation of the response contents.

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

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

The tool takes no arguments and the schema confirms this, so there is no parameter semantics burden. The description explicitly states 'Takes no arguments,' giving an agent complete clarity with zero ambiguity.

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

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

The description uses a specific verb ('Report') and names the exact resource and scope: the current authenticated account and its organization. It enumerates the returned fields (user id, email, name, org id, org name, orgs list with current one marked), which clearly distinguishes it from the app-management sibling tools.

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

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

The description explicitly states when to call this tool: before publishing when the person named an organization to publish into. It also tells the agent to stop if the returned org id does not match the named organization, and explains where switching occurs externally.

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