reachpad-mcp

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

The annotations only say the tool is not read-only, not idempotent, and not destructive, so the description carries most of the side-effect burden. It discloses the important live-at-once behavior, the default org_link access, and the need to pre-confirm content and destination with the user, which goes beyond the annotations. It does not detail reversibility or failure limits, but the schema covers other conditional behaviors.

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, each earning inclusion: immediate action, pre-confirmation caution, and access default. The most critical operatonal fact — that version 1 goes live and is not pending — 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?

Given the complex schema, the description does enough to call safely for a first publish: states the outcome, the immediate visibility, and access default. The validate parameter has a different return shape but that is fully documented in its own property description, so the header note is a reasonable omission and not a fatal gap.

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

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

Input schema coverage is 100%, so the baseline is 3. The description adds some semantic context about access ('lets anyone signed in to the same organization open the link') but does not meaningfully expand on the remaining parameters beyond the already rich 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 states a specific verb and resource: 'Publish new files as an app and get its URL back.' The phrase 'Version 1 goes live at once' distinguishes this creation flow from version updates, matching the title and separating it from sibling tools like update_app and 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?

It gives a clear precondition — 'show the person the content and destination before calling this' — which implies the user-facing review needed before an immediate public/org-visible publish. However, it does not explicitly say when to prefer update_app or publish_app_version over create_app, so the alternatives are only implied by context and the title.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: unexpected responses for file-serving apps and function apps, plus a recommended fallback behavior, which goes beyond what annotations state.

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

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

The description is compact and front-loaded: the first sentence states the core action clearly, and the next two sentences add necessary caveats and a workaround. Every sentence carries useful information without redundancy.

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

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

For a read-only log tool with no output schema, the description covers the main operation, edge cases, and fallback guidance. It omits details about the exact return shape, but that is less critical given the annotations and the clarity of the core use case.

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 100% of parameters with clear descriptions, including defaults and constraints. The tool description does not add significant parameter-level meaning beyond the schema, 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 states a specific verb and resource: 'Read recent log lines from the live version of a function app.' This clearly differentiates it from sibling tools like read_app_file or read_app_version, which handle files or version metadata rather than logs.

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 practical guidance about when logs will or will not be available: apps serving files have no process, and function logs are not captured yet. It also gives an actionable workaround (have the function catch its own errors), though it does not name alternative tools because none exist for logs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description aligns with these by stating a list operation, but it does not add extra behavioral context beyond what annotations provide. No contradiction, but no additional insight either.

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

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

The description is concise, consisting of two sentences that convey all necessary information without redundancy. It is well-structured and to the point.

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 operation, the description sufficiently explains what information will be returned (people, roles, grant status). No output schema exists, but the description covers the needed context without gaps.

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

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

The single parameter app_id is fully described in the schema with additional useful details (e.g., 'returned by search_apps or create_app' and 'starts with app_'), which goes beyond just the type and provides practical guidance for filling the parameter. Schema coverage is 100%.

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 purpose: listing people an app is shared with, their roles, and grant attachment status. It uses a specific verb ('list') and specifies the resource (app shares), distinguishing it from sibling tools like share_app or revoke_app_share.

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 usage for retrieving share information but does not explicitly differentiate when to use this tool versus alternatives (e.g., share_app or revoke_app_share). No direct when-to-use or when-not-to-use guidance is provided.

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 adds meaningful behavioral context: versions are immutable, numbered from 1, earlier versions are editor-only, and the live link follows the app's access setting. This helps the agent understand what the operation exposes without claiming any mutation.

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

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

Four sentences, all earning their place: core purpose, ordering, visibility/access context, and pagination. No filler or 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?

The description is complete enough for selecting and invoking the tool safely: it covers ordering, immutability, access behavior, and pagination. The only minor gap is that there is no explicit description of the return shape, but no output schema exists and 'List versions' makes the expected return type reasonably inferable.

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 app_id, limit, and cursor. The description mentions the next_cursor pagination pattern, but this largely duplicates the cursor field's schema description rather than adding new parameter semantics.

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

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

The description states a specific verb and resource: 'List an app's versions, newest first.' The collection scope clearly distinguishes it from sibling read_app_version (single version fetch) and publish_app_version (creation).

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

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

The description gives clear context for pagination with next_cursor, but it does not explicitly say when to prefer this tool over read_app_version or publish_app_version. Usage is implied rather than directly stated, so it earns the minimum viable score.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond annotations: the returned metadata includes names, setters, timestamps, and bound app versions, and that even the full tool ecosystem will never expose secret values. This direct disclosure of the tool's security boundary is valuable.

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

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

The description is two tight sentences with no wasted words. The core action and scope are front-loaded, the output composition is stated compactly, and the important 'no secret values' limitation earns its place. Every sentence 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 listing tool with annotations covering read-only/idempotent behavior, the description covers everything an agent needs: what is listed, the organizational scope, the fields returned, and the all-important fact that secret values are unreachable. With no output schema present, this description adequately replaces it.

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

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

There are zero parameters, so the schema leaves nothing for the description to compensate for. The description still helps by defining the scope ('organization's secrets') and the output fields, which is more than the empty schema provides. A score of 4 is appropriate for a parameterless tool.

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

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

The description uses a specific verb ('List') and a clear resource ('the organization's secrets'), and precisely enumerates what is returned: each name, who set it, when, and the bound app versions. It also clarifies the scope boundary with 'Names only' and the security guarantee that no tool returns secret values. This unambiguously distinguishes list_secrets from mutation siblings like set_secret and remove_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 makes clear this tool is for obtaining a read-only inventory of secrets, including who set them and which app versions bind them. It also tells the agent that no tool anywhere returns secret values, which prevents futile attempts to retrieve actual secret content. It does not explicitly name sibling alternatives, but the listing purpose is not easily confused with create/update/delete operations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds non-redundant behavioral context: it clarifies the non-recursive scope ('directly inside'), names the returned item types (subfolders and apps), and reveals a useful output field ('updated_at') relevant to the sibling '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?

Two sentences with no filler: the first states the core action and scope, the second gives usage and cross-tool context. Every sentence earns its place and the most critical behavioral detail 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 simple read tool with two optional, fully documented parameters and safety annotations, the description covers the essential behavior, top-level invocation, and a relevant return field. It does not enumerate the full return format, but that gap is minor given the tool's simplicity and the existing schema documentation.

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

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

Schema description coverage is 100%: both 'limit' and 'folder_id' are documented with defaults and usage. The description only restates the folder_id omission guidance already in the schema, adding no new parameter-level meaning. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description states a specific verb ('List') and resource ('what is directly inside one folder'), and clarifies the content ('subfolders and the apps filed in it'). The phrase 'directly inside one folder' implicitly distinguishes it from the recursive sibling 'tree', making the tool's 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?

Provides clear usage context: how to list the top level ('Omit folder_id for the top level') and why this tool matters for a downstream workflow ('Each folder carries the updated_at that mv needs'). It does not explicitly name alternatives or when-not-to-use scenarios, so it falls short of a full 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 provide only readOnlyHint=false, idempotentHint=false, and destructiveHint=false, which carry limited behavioral weight. The description adds the key nested-folder behavior, but does not mention failure modes such as duplicate folder names, missing parent folders, or permission requirements.

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

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

The description is a single sentence with no filler: verb, resource, and scope are front-loaded. Every part earns its place for this simple tool.

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

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

For a two-parameter tool with one required parameter and full schema coverage, the description plus schema provide enough to invoke it correctly. It could optionally mention return values or duplicate-name behavior, but those are minor omissions for such a straightforward operation.

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

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

Schema description coverage is 100%: both 'name' and 'parent_id' already have clear descriptions. The tool description adds only a plain-language restatement of nesting behavior without new constraints or syntax, so it falls at the baseline for fully covered schemas.

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 ('Create') and resource ('folder'), and adds useful scope: 'at the top level or inside another one.' This clearly separates mkdir from filesystem siblings like rmdir, ls, and mv, and from unrelated app-level 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 makes the primary use case clear—creating a folder, either at the top level or nested—and implicitly explains when parent_id should be provided versus omitted. It does not explicitly name alternatives or when not to use the tool, but no sibling tool directly competes with this action.

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 (readOnlyHint false, idempotentHint true, destructiveHint false), the description reveals an important behavioral guard: stale reads are refused rather than silently overwriting another user's move. It also discloses the exactly-one-of-two-identifiers rule, adding meaningful behavioral context beyond what annotations 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 sentences with no wasted words. The main action is front-loaded, followed by the exclusivity rule, destination semantics, and the stale-move guard. Every sentence contributes 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?

For a mutating tool with four parameters and no output schema, the description covers the core operational requirements: what can be moved, exclusivity, destination behavior, and the conditional base_updated_at requirement. It does not describe the return value, but this is a minor omission for a move operation.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds value by explaining the relationship between parameters: exactly one of app_id/folder_id, top-level use of null to_folder_id, and the necessity of base_updated_at for folder moves. This goes beyond the field-level 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 states a specific verb and resource: move an app or folder. It precisely distinguishes the two use cases (app into folder, folder under folder) and differentiates itself from read-only siblings like ls and tree by describing a mutation operation.

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

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

The description gives clear usage constraints: name exactly one of app_id or folder_id, use to_folder_id as destination or null for top level, and provide base_updated_at when moving a folder. It mentions that base_updated_at comes from ls or tree, giving practical guidance, though it does not explicitly list alternative tools.

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

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

Annotations already mark the call as non-read-only, idempotent, and non-destructive; the description adds useful context by stating 'Nothing is rebuilt, the pointer moves,' explaining that rollback is a pointer change rather than a rebuild or destructive operation. No contradiction with annotations exists.

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

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

Three sentences, front-loaded with the core action, followed by the workflow context and a compact explanation of the underlying mechanism. Every sentence earns its place and there is no filler.

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

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

For a simple two-parameter operation with no output schema, the description covers what the tool does, when it is used, and what happens to the app link. It lacks explicit error/precondition notes such as whether the named version must already exist, but this is minor for an idempotent pointer-move operation.

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

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

Schema coverage is 100%, so the schema fully documents app_id and number. The description reinforces that number is the version to make live and that older numbers trigger rollback, but it does not add significant new parameter 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 opens with a specific verb-resource pair: 'Make one version of an app live by its number.' It also clarifies the semantics in terms of the existing staged/publish-false workflow and rollback, so an agent can distinguish it from version-reading tools like list_app_versions and read_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 conditions for use: it is how a staged version goes live and how an older version is rolled back. It does not explicitly name sibling alternatives or list when-not-to-use cases, but the use scenarios are unambiguous.

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

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

Annotations carry almost no signal (three false hints), and there is no output schema, so the description does the full disclosure burden: it reveals that schema-changing statements are enforced/refused, that only owners and editors may invoke it, and exactly what comes back ('rows and rowCount for a select', 'changes with lastInsertRowid for a write'). This return-format disclosure is essential and well handled. Nothing contradicts the annotations.

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

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

Four sentences, each carrying distinct value: purpose, schema exclusion, permission, and return shape. The core purpose and scope are front-loaded in the first sentence, and there is no redundant or filler wording — 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 3-parameter tool with no output schema, everything needed for correct invocation is present: which app and SQL to pass (via schema), what the tool does, what it refuses, who may run it, and what it returns for both read and write statements. Error-case behavior is not described but is not required for correct 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 schema already documents sql, app_id, and params including the single-statement rule. The description reinforces the one-statement constraint and the select-vs-write distinction, but adds no per-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?

Opens with a specific verb+resource+goal: 'Run one SQL statement against a function app's own database, to read rows and to fix data.' The scope is pinned down by 'one statement' and the refusal of schema changes, and no sibling tool handles SQL against the app DB, so an agent can distinguish it without opening any other schema.

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

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

The description states when to use the tool (read rows, fix data) and gives an explicit when-not: 'a table or a column belongs in the version's migrations/NNNN_name.sql, and a statement that changes the schema is refused.' It routes schema work to the migration workflow rather than to any sibling tool by name, and adds an owner/editor prerequisite. Naming a direct sibling alternative would have made it 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 set readOnlyHint/idempotentHint/destructureHint, and the description adds real behavioral facts: files carry contents, content_omitted/too_large markers, and the meaning of version, head_version, and pending_version. The disclosure is comprehensive, though the wording is occasionally garbled ('content_omitted answer budget did not fit').

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 dense paragraph with run-on sentences and unclear pronoun references ('that staged version', 'where that is not the live one'). It front-loads the purpose but sacrifices readability and structure, making it harder to parse than necessary.

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

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

No output schema exists, and the description does attempt to cover the important return fields and file-content handling. However, the confusing syntax and ambiguous references leave gaps that an agent must resolve through trial or other tools.

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

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

The only parameter, app_id, is already fully documented in the schema (100% coverage). The description doesn't add parameter-level semantics; it focuses on output fields, which is appropriate, 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 opens with 'Read one app before update_app', specifying the verb, resource, and the workflow slot. It distinguishes the tool from read_app_file and publish_app_version by naming those siblings for file content and publishing.

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 usage guidance: call before update_app, pass base_version_id to update_app, use read_app_file for files whose content is omitted or too large, and rely on publish_app_version to make a staged version live. This fully routes an agent between 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 a safe read-only, idempotent operation. The description adds meaningful behavioral details: the 256 KB limit, refusal rather than truncation for non-text or oversized files, and the default-to-newest-version behavior with consistency to read_app's version listing. 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?

Four compact sentences, each earning its place: main purpose, usage trigger, size/type constraint, and version behavior. The most important scoping information 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 simple read-one-file tool with no output schema, the description is complete: it specifies the return type (text), size cap, refusal behavior, and version selection. The agent has enough information 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 schema already documents app_id, path, and number. The description adds useful cross-tool meaning for the number parameter: the version is the same one read_app lists, which helps the agent pick the correct version 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 clearly states the operation: read one file out of an app as text, at most 256 KB. It also distinguishes itself from read_app by specifically targeting files omitted with content_omitted and by fetching a single file without the rest of the 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?

It explicitly tells when to use the tool: for files that read_app left out due to the answer budget, or to fetch a single file. It also warns that non-text and oversized files are refused, giving the agent clear criteria for avoiding misuse.

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 annotations, the description clarifies important behavior: it shows the live preview and returns 'no picture' rather than an error if a capture has not been generated yet. This helps set expectations.

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

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

The description is informative but somewhat wordy and awkwardly phrased, with repetitive references to 'picture' and 'app's link serves.' It could be more direct while retaining the key usage and edge-case guidance.

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

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

Given there is no output schema, the description compensates by indicating the result is an image and by explaining the no-preview behavior. It covers the main contexts an agent needs, though it could be slightly clearer about output format.

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 app_id parameter, so the baseline is 3. The description does not add extra meaning about app_id 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 states the tool provides a picture/screenshot of an app's current live rendered state, which is a clear resource and action. It also differentiates from file-reading tools by noting it is for apps whose files you cannot read.

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

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

The description explicitly says to use this tool when you cannot read an app's files, such as a function app whose module remains with developers. It also notes it returns the live version only, giving practical selection guidance.

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

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

Beyond the readOnlyHint, idempotentHint, and destructiveHint annotations, the description adds useful behavioral context: earlier versions are open to the app's editors, while the live link follows the app's access setting. This helps the agent reason about visibility and 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?

Three purposeful sentences with no filler. The core action is front-loaded, followed by use cases and an important access nuance. 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 read tool with no output schema, the description adequately explains that the result includes files and each text file's content, plus access-relevant behavior. It does not detail the exact response structure, but that is not essential for this level of 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 description coverage is 100%, so both parameters are already well documented. The description adds no additional parameter-level meaning beyond saying 'by its number,' which is sufficient given the schema's clarity.

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

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

States a specific verb and resource: 'Read one version by its number, with its files and each text file's content.' This clearly distinguishes it from siblings like list_app_versions (which lists versions) and read_app_file (which reads a single 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?

Gives clear use cases: inspect what an earlier publish contained and copy a file back out of a version. It provides clear context for when to use the tool, though it does not explicitly name alternatives or state when not to use it.

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

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

Beyond the annotations, the description discloses what gets destroyed (the secret and its binding in every published version), how failures are surfaced (version kept in the list with status failed), and the retry behavior. This is exactly the context annotations alone would 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?

The description is compact, front-loaded with the core operation, and every sentence contributes meaningful behavior or failure semantics. There is no redundance 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?

For a single-parameter destructive tool, the description explains the scope, failure state, and retry behavior, making it largely complete. It does not describe authorization requirements or the exact return format, but these are not critical for invoking 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 schema already covers 100% of parameters and describes name as 'The secret name, from list_secrets.' The description adds no additional parameter semantic detail, 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 clearly states the action: remove one organization secret and delete it from every published version that binds it. This is a specific verb-resource pair that distinguishes 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 description gives clear context for use: it removes an organization secret and handles partial failures by allowing the operation to be retried. It does not explicitly contrast with alternatives, but the intended usage is well implied.

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 explicitly states 'The app itself is untouched,' clarifying that the operation only affects the share, not the app. Combined with the annotations (readOnlyHint false, destructiveHint true, idempotentHint true), the behavior is transparent. It does not describe side effects like notifications, but the core destructive action is clear and consistent with 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 two concise sentences that pack all essential information: action, target, scope, permission context, and non-destructive nature. There is no redundancy, fluff, or unnecessary detail. Every word serves a purpose, making it highly efficient.

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

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

Given the simplicity of the tool (2 parameters, no output schema), the description is complete. It covers what the tool does, who can use it, under what condition, and clarifies the effect on the app. No critical information is missing for a typical caller to understand and invoke the tool correctly.

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

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

The schema provides 100% coverage for both parameters, including format hints ('Starts with app_', 'Starts with shr_'). The description adds relational context by indicating the share id comes 'from list_app_shares,' and both parameters are referenced in the description. This goes beyond the schema's baseline, giving additional meaning about how the parameters relate.

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 ('Remove one share by its id'), the target resource ('share'), and the scope ('by its id'). It also clarifies that the app itself is untouched, and specifies the intended user role (owner or editor) and condition (editor-managed sharing enabled), leaving no ambiguity about the tool's 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 provides explicit usage conditions: 'The owner or an editor may use this when editor-managed sharing is enabled.' It also implicitly distinguishes from adding shares by referencing list_app_shares, though it does not name an alternative tool for adding shares. This is sufficient guidance for when to use the tool, but could be slightly more explicit about 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 already indicate destructiveHint=true and readOnlyHint=false, so the mutation is known. The description adds useful behavior beyond that: it refuses on non-empty folders and guarantees it never deletes an app, giving the agent a precise safety boundary. No contradiction with 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 with no filler. The first sentence states the core operation, and the following sentences add necessary constraints and usage guidance. Information is front-loaded and 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 one-parameter tool with no output schema and destructive/idempotent annotations, the description is complete: it defines the operation, the precondition, the refusal condition, and the safe next step. An agent has enough context to call it correctly without needing additional details.

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 folder_id fully with a description, so the baseline is 3. The tool description adds no direct parameter-level detail, but its constraints about empty folders and not deleting apps indirectly help an agent choose the correct folder.

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 operation as deleting a folder, with the critical precondition that it must be empty. It also distinguishes itself from app-related tools by stating that it never deletes an app, which prevents confusion with sibling 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 an explicit usage condition: the folder must be empty, and it refuses if apps or subfolders remain. It also recommends moving contents out first. It does not name an alternative sibling tool such as mv, but the workflow implication 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 annotation already marks the operation as read-only and idempotent. The description adds useful behavioral detail about search semantics and states that the result includes ids and live URLs, going beyond the annotation.

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 is concise, but the second sentence contains the confusing 'not meaning: search for a word...' clause, which muddies the structure and could be clearer.

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 states scope (caller's organization), matching behavior, and return contents (ids and live URLs). With no output schema, it could be more explicit about result shape, but it provides enough context for a search operation.

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

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

The schema has 100% description coverage for all five parameters, so the baseline is 3. The description does not add significant extra meaning beyond repeating the general search behavior.

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

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

The description opens with a clear verb and resource: 'Find apps in the caller's organization by text.' It also specifies matching behavior (substrings of name/slug, whole words on the live page) and return type (ids and live URLs), but the awkward phrase 'not meaning...' introduces some confusion.

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: it is a text search over apps in the caller's organization, so an agent would use it when searching by text rather than known app IDs. However, it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already indicate this is a write operation (readOnlyHint false) that is idempotent and non-destructive. The description adds meaningful behavioral context beyond annotations by clarifying the owner-only restriction and the public-link-only scope for password and expiry.

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 concise sentences with no filler. The primary action and access levels are front-loaded, and the remaining sentences add only necessary constraints ('Owner only' and public-link-specific behavior).

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

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

For a 6-parameter tool with no output schema, the description covers the essential call-time facts: available levels, level semantics, the owner-only permission, and the conditions under which password/expiry apply. It is slightly thin on how 'named people' are managed, but this is partially covered by the sibling tool share_app.

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 high at 83%, with most parameters already described in the schema. The description adds value by explaining that password and expiry parameters only apply to public_link, which clarifies the relationship between level and the optional clear_password/clear_expiry fields.

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

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

The description uses a specific verb ('Change') and a clear resource ('who can open an app'), then enumerates the three exact levels: restricted, org_link, and public_link. It does not explicitly differentiate itself from sibling tools like share_app, but the access-level framing makes the tool's purpose easy to identify.

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 useful context such as 'Owner only' and 'password and an expiry apply to a public link only,' which guide when the tool is applicable. However, it does not explicitly state when to prefer set_app_access over alternatives like share_app or update_app, leaving some routing to inference.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true), the description discloses key behaviors: replacing existing values, rotating to every published version binding the secret, and reporting affected version counts and failing IDs. It also notes organization-wide member access, adding real context 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 dense sentences with no filler. The core action is front-loaded, followed by update/rotation semantics and the response shape, so 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 the schema covers parameters and the description covers permissions, upsert behavior, version rotation impact, and return value, nothing essential is missing for an agent to select and invoke this 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 description coverage is 100% and both name and value are already fully documented in the schema. The tool description reinforces that the name is what functions bind, but does not add new parameter-level meaning; 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?

Description states a specific verb and resource: 'Set one organization secret.' It clearly distinguishes from siblings like remove_secret and list_secrets by describing the manifest-binding purpose and the replace-on-existing-name behavior.

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: secrets are set so functions can bind them by name in manifests, and re-setting an existing name replaces/rotates it. It does not explicitly contrast with remove_secret or list_secrets, but the intended use is strongly implied and unambiguous.

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

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

The description explains the behavior for addresses without an account (grant starts working at first sign-in), adding valuable detail beyond the annotations. The annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) are consistent with the description, which describes a non-destructive, idempotent sharing action. The description does not mention error cases or side effects, but the core behavior is 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?

The description is concise, consisting of two sentences that directly convey the action, the condition, and the special case for new accounts. No unnecessary words or redundancy, and it is well-structured for quick comprehension.

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 (3 required parameters, no output schema, no nested objects), the description provides all necessary context: who can use it, under what condition, and how the grant behaves for new users. It is fully complete for an agent to invoke the tool correctly without further information.

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 covers all three parameters with helpful descriptions (e.g., app_id starts with 'app_', role enum with explanatory text). The tool description adds extra context for the email parameter ('An address without an account gets a grant...') that is not present in the schema, thus enhancing parameter understanding beyond the schema's 100% 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 action ('Give one email address access to an app') and specifies the two possible roles (viewer or editor). It also distinguishes this tool from siblings by noting the permission requirement (owner or editor) and the condition (editor-managed sharing), making the tool's 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 provides a clear condition for when the tool can be used ('when the owner has enabled editor-managed sharing') and specifies authorized users (owner or editor). It does not explicitly name alternative tools (e.g., revoke_app_share) but the context makes the appropriate use case evident, so it earns a high score.

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 it as destructive/not read-only, but the description adds crucial behavior beyond that: the app link stops immediately, the app and versions are retained, restoration is possible, and permanent deletion only occurs at the Trash URL. This is exactly the kind of context an agent needs.

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

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

Three short sentences front-load the action and effect, then pack ownership, retention, restoration, and permanent-deletion distinction into the closing sentence. Every clause earns its place; no filler.

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

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

For a single-parameter mutation tool, the description covers what happens on invocation, who can invoke it, that data is recoverable, and where permanent deletion occurs. The absence of an output schema is not a gap because no return value is needed for an agent to call this 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 fully documents the only parameter, app_id, including its origin and prefix convention, so the description need not add parameter-level detail. The description adds no parameter semantics, but schema coverage is 100%, so the baseline 3 applies.

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

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

States a specific verb ('Move') and resource ('an app') with target 'trash', and immediately clarifies the practical effect ('Its link stops opening at once'). The description also distinguishes from permanent deletion by noting the trash is the only place an app is deleted for good, which separates it from any destructive deletion intent among 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?

Provides clear context and constraints: owner-only access, immediate effect, and restorability. It stops short of naming a sibling alternative or an explicit 'when not to use' statement, though the permanent-deletion note implies the trash interface is the alternative for full deletion.

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

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

Annotations already declare readOnlyHint true, idempotentHint true, and destructiveHint false, covering the safety profile. The description adds meaningful behavioral detail about the output: the whole tree is returned, nested, with per-folder app counts and top-level count, and each node carries updated_at. This goes beyond the annotations and gives the agent a concrete picture of what the call returns.

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. The core purpose is front-loaded, and the additional detail about counts and updated_at adds value without bloating the definition.

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

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

For a zero-parameter, read-only tool with no output schema, the description covers the essential return elements: hierarchical structure, app counts per folder, top-level count, and updated_at. It could be more explicit about the exact data shape or output format, but there is no missing information an agent would need 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?

The tool has zero parameters, so the baseline is 4. There is no schema burden for the description to compensate for. The description's focus on output content rather than any input shape 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 identifies the tool as returning the organization's entire folder tree in nested form, with counts of apps per folder and at the top level. It is distinguishable from the sibling 'ls' tool, which likely lists a single folder's contents, though it does not explicitly name that alternative.

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

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

The description implies use cases by mentioning the nested tree and the updated_at needed by 'mv', but it does not explicitly state when to use this tool versus siblings like 'ls' or 'mkdir'. There is no exclusionary guidance or alternative routing, leaving the agent to infer placement from the description.

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

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

Annotations only provide readOnlyHint=false, idempotentHint=false, destructiveHint=false, leaving behavioral burden to the description. The description thoroughly discloses side effects: 'replace publishes files as the whole file set: anything left out is gone,' merge semantics, that base-a-move is refused rather than overwritten, that it goes live immediately unless review/publish=false, and that two merges build on each other. It also notes validation side-effects (returns file set, bytes, entry, kind) and the org limit failure case. No annotation 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 long but dense, covering many behaviors without fluff. It is front-loaded with the core action and prerequisite, then explains modes, validation, and staging. Despite being a single paragraph, each sentence earns its place. Minor improvement could be bullet points, but the structure is logical and readable.

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 complex (9 params, nested objects, no output schema), and the description covers almost everything an agent needs: prerequisites, mode semantics, validation return info, staging, merge accumulation, manifest replacement rules, and failure modes. It omits a general description of the return value for the normal publish call (unlike the validate case), but references SKILL.md for runtime details. This is near-complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds substantial meaning beyond the schema. For example, it explains merge mode in the narrative, clarifies that files are plain text not base64, describes how functions with db include migrations, and links to SKILL.md for runtime details. It also clarifies base_version_id semantics ('the version this edit builds on') and the behavior of validate and publish flags. This goes well 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 states a clear specific verb and resource: 'Publish a new version of an existing app.' It distinguishes itself from create_app (new app) and publish_app_version (making a staged version live) by explicitly naming the latter and explaining the staging flow. 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 explicit workflow guidance: read the app first, pass base_version_id, and mentions alternatives like publish_app_version for later publication. It explains when to use merge vs replace, when to use validate=true, and when to use publish=false for staging. It also warns about refusal conditions (base moved, path not in base). This is comprehensive usage 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?

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description goes beyond this by detailing the output fields, the fact that the current org is marked within the orgs list, and the connection-follows-org-switching behavior, which adds meaningful behavioral context without contradicting 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 two sentences: the first states the tool's output and the second provides essential usage logic. It is front-loaded and every sentence earns its place, with no redundant filler.

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

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

For a zero-argument, read-only tool, the description is complete: it enumerates the expected output fields and gives a concrete workflow directive (check before publishing, compare org id). No output schema exists, but the description sufficiently covers what the agent needs to call and interpret 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?

The tool has zero parameters, and the schema is empty, so the baseline is 4. The description confirms 'Takes no arguments,' which adds no new semantics but also requires no parameter documentation.

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

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

The description clearly states the tool reports the account and organization the connection is signed in as, listing specific fields (user id, email, name, org id/name, and orgs). This distinguishes it from the sibling app-management tools, which all target app operations rather than identity/connection context.

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 concrete usage guidance: call before publishing when the person named an organization to publish into, and stop if the org id doesn't match, with switching done at reachpad.dev/apps. It lacks explicit alternatives or when-not-to-use guidance, but the context is clear enough to direct an agent.

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