Charming

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the write/destructive nature is known. The description adds critical behavioral context: synchronous execution ('when it returns, the app is already live'), replacement semantics for same manifest.id, and the immediate accessibility of the result. These go beyond annotations to clarify the tool's operational behavior.

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

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

The description is lengthy but every sentence earns its place. It is front-loaded with the core purpose and synchronous behavior, then flows into replacement semantics, parameter guidance, and fallback policy. While it could be trimmed slightly, the structure is logical and the density of useful information justifies the length.

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

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

Given the tool's complexity (5 parameters, destructive behavior, replacement semantics, and integration with other features like storage and fallback), the description covers all critical aspects. It explains when creation is safe, how state persists, and how to handle unsupported requests. The presence of an output schema reduces the need to describe return values, but the description still provides necessary behavioral context.

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

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

All five parameters have schema descriptions (100% coverage), so the baseline is 3. The tool description does not repeat parameter definitions but does add context for some parameters indirectly (e.g., mentioning fill-viewport rule for ui, storage semantics for module). However, the added value is marginal because the schema already provides detailed parameter explanations.

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

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

The description begins with 'Create a new interactive web app and render it inline.' It clearly identifies the verb (create) and resource (interactive web app). It distinguishes from sibling tool update_app by noting that create_app uses manifest.id ownership to replace, while update_app edits by UUID. This differentiation makes the purpose unambiguous.

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

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

The description states 'Use this to build a new app from a request.' It provides explicit guidance on when to use this tool versus update_app, and includes a detailed fallback policy for tasks Charming cannot handle: 'don't fake it — build the closest local-state version and log the gap with submit_feedback.' This covers both appropriate use and 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?

Beyond annotations (destructiveHint=true), the description adds context: permanent deletion, optional purge, irreversibility, and detailed confirmation mechanism with fallback behavior for hosts that cannot show a prompt.

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

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

Three concise sentences, front-loaded with the core action, followed by usage guidance and important behavioral notes. No unnecessary words.

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

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

Given the tool's complexity (deletion with confirmation and optional purge), the description fully covers the behavior, including host-dependent confirmation logic and irreversibility warning.

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 parameters. The description adds value by explaining the confirm parameter's role and fallback behavior, and mentioning purge_storage option, but does not add extensive new detail.

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

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

The description explicitly states the verb 'delete', the resource 'Charming app', and the scope 'the caller owns'. It also mentions optional data purging. This clearly distinguishes it from sibling tools like update_app or rename_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 says 'use this to remove an app the caller no longer wants' and provides critical guidance on irreversibility and confirmation requirements. However, it does not explicitly state when not to use this tool or list 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 declare readOnlyHint=true; description adds that it returns 'live embedded UI' and 'callable API operations', and warns about the url field embedding a write-capable token. This provides useful behavioral context beyond 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 adding value; front-loaded with core purpose. Could be slightly more concise but well-structured.

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

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

Complete description covering purpose, usage flow, output composition, and important distinction between shareUrl and url. No gaps given annotations and output schema existence.

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

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

Schema coverage is 100% with a clear description and pattern for app_id. Description adds minimal value beyond schema (implies ID comes from list_apps). Baseline 3 is appropriate.

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

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

Description clearly states the verb 'Fetch' and resource 'app by ID', and distinguishes from sibling tool list_apps by explicitly contrasting metadata vs rendering.

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 when-to-use instructions (open, re-render, continue working) and advises to call list_apps first to find the ID. Includes a specific warning about using shareUrl instead of url, but no explicit when-not-to-use beyond that.

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 and destructiveHint=false. Description adds optimism-concurrency version detail, aligning with safe read behavior. No contradictions.

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

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

Two sentences, front-loaded with purpose and content summary, no wasted words.

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

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

Low complexity tool with one parameter and output schema; description covers purpose, usage, and return content completely.

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

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

Schema has 100% coverage with detailed format description for app_id. Description adds no additional meaning beyond schema, meeting baseline.

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

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

The description clearly states it returns app source (module, UI script, styles) and version, distinguishing it from siblings like get_app (metadata) or mutate_app (modification).

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

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

Explicitly says use for inspecting, debugging, or editing owned apps, providing clear context. Lacks explicit when-not-to-use or alternatives, but sufficient.

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

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

Annotations declare readOnlyHint=true, and the description adds extensive behavioral context: details of returned fields (id, role, displayName, etc.), role explanations, pagination mechanics, and notes about null descriptions. This goes well beyond annotations, offering rich transparency.

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

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

The description is front-loaded with the main purpose and well-structured, but it is somewhat verbose with detailed role explanations. However, every sentence contributes useful information; no redundancy.

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

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

Given the tool's complexity (paginated list with multiple roles and fields), the description is highly complete. It explains output semantics, pagination, null descriptions, and usage of shareUrl. The presence of an output schema does not diminish the value of this clarity.

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

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

Schema coverage is 100%, so the schema already documents both parameters (limit, cursor) with descriptions. The description adds value by explaining pagination flow ('Paginate with cursor from a prior call's nextCursor line'), which is not present in schema descriptions. This provides helpful usage context.

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

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

The description clearly states the tool lists the caller's Charming apps including owned and shared ones, with a specific verb ('List') and resource ('apps'). It distinguishes from siblings like 'get_app' by noting this is for finding an app's ID before fetching, editing, or calling 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 explicitly says 'Use this to find an app's id before fetching, editing, or calling it,' providing clear context for when to use this tool. It also explains pagination and how to use returned data (e.g., using shareUrl). However, it does not explicitly state when not to use it compared to 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 readOnlyHint=true, so description's behavioral disclosure is less critical. Yet description adds value by explaining the meaning of status and role fields in output, providing context beyond 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?

Single sentence packs significant detail about output labeling. Though lengthy, it is efficiently structured. Minor improvement could be splitting roles/statuses for easier parsing.

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 output schema present and one well-documented parameter, description covers core purpose and output. Could mention lack of pagination or ordering, but not critical for simple listing.

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

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

Only one parameter (app_id), fully covered by schema description. Tool description does not add additional parameter semantics beyond what schema 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?

Description clearly states the tool lists who an app is shared with, and provides specific details about output (status and role labels). Distinguishes from sibling tools like share_app and unshare_app which modify 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?

States 'Use this to see who an app is shared with', which is clear. However, no explicit when-not-to-use or comparisons to siblings like list_apps or list_feedback. Implied but not direct.

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?

Adds key behavioral details beyond annotations: owner-checked, pagination with cursor, newest-first ordering. Annotations already indicate read-only and non-destructive, which the description does not contradict.

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

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

Four sentences, no fluff. The first sentence states the purpose, followed by usage guidance and key behavioral notes. Efficient and well-structured.

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

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

Covers core functionality: listing feedback, filtering by app, pagination, ordering. Output schema exists for return values, so description is sufficient. Minor omission: no mention of error handling or rate limits, but acceptable for a read-only list tool.

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

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

Schema coverage is 100% with descriptions for all parameters. The description rephrases behavior for app_id but does not add new meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the action (list) and resource (feedback rows for caller's apps). It distinguishes from sibling tools like submit_feedback (write) and list_apps (different resource). The phrase 'owner-checked' adds specificity.

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

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

The description explicitly says 'Use this to review feedback previously recorded for an app,' providing clear context. It explains behavior with and without app_id, but doesn't explicitly mention when not to use or alternatives beyond the implied alternative of submit_feedback.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. Description adds that operations change state and that read/write safety may be uncertain. No contradictions, but could elaborate on what gets destroyed.

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 directly stating purpose, usage guidelines, and fallback. No redundant words, front-loaded with key information.

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

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

Covers what the tool does, when to use it, and how to discover operations. Mentions returning a result. Output schema exists, so return details are not needed. Missing explicit mention of parameter passing but schema addresses it.

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

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

Schema covers 100% of parameters with descriptions. Description adds no extra param details beyond what schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool runs a mutating backend operation on a Charming app, distinguishing it from read-only query_app. It specifies 'without editing code' to avoid confusion with code editing 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?

Explicitly says use for operations that change state, for read-only use query_app, and if operation name is unknown call get_app. Provides clear when-to-use and when-not-to-use guidance with named 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 readOnlyHint=true and destructiveHint=false. The description adds that it returns results and does not edit code, but lacks detail on error handling or behavior if op is invalid.

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, no wasted words, sufficiently detailed without being verbose.

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

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

For a tool with 3 parameters and an output schema, the description provides complete context: purpose, usage, and sibling differentiation. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add any additional meaning beyond the schema's parameter descriptions.

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

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

The description clearly states the verb 'run' and resource 'backend operation on a Charming app', and explicitly distinguishes from mutate_app by noting it is read-only and does not edit code.

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 when to use (read-only operations) and when not (state changes, use mutate_app). It also advises calling get_app if unsure which operation or 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?

Adds critical behaviors: old URL redirects, shareUrl vs url distinction. Annotations only hint at mutability; description fill gaps with no contradictions.

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

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

Five purposeful sentences with no fluff. Key action and constraints front-loaded; every sentence adds value.

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

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

Given output schema exists, description covers purpose, behavior, parameter rules, and result guidance (shareUrl). Complete for a mutation tool with moderate complexity.

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

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

Schema already describes both parameters (100% coverage). Description adds processing details ('lowercased and trimmed') and validates slug format, exceeding schema baseline.

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

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

The description clearly states the tool changes an app's URL slug, distinct from title/machine id, and differentiates from update_app and other 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?

Explicitly says when to use (give app a different public URL) and contrasts with update_app. Lacks explicit 'when not to use' but context is clear.

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

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

The description adds significant behavioral context beyond annotations: it explains that changing the handle changes app URL prefixes, old handles redirect, and it is rate-limited. Annotations indicate it is not read-only and not destructive, which aligns with the description. No contradictions.

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

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

The description is a single block of text that is informative yet concise, with no wasted words. It front-loads the core purpose and then adds important details. Slightly better structuring (e.g., bullet points for rules) could improve readability, but it is adequate.

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

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

For a simple mutation tool with one parameter, the description covers all essential aspects: purpose, effect on URLs, scope (current user), handle rules, rate limits, and that old handles redirect. An output schema exists (though not detailed in the input), so return value explanation is not needed.

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

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

The input schema has 100% coverage for the single 'handle' parameter, with description covering rules. The tool description adds value by reiterating these rules in context and mentioning that input is lowercased and trimmed, providing extra clarity beyond the schema.

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

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

The description clearly states it changes the handle (username) of the signed-in user, explains what a handle is (first segment of URLs), and specifies it acts on the current user only. No sibling tools have similar functionality, so it stands out.

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

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

The description explains when to use the tool (to change handle) and provides context such as old handle redirecting and rate limiting (3 per 30 days). It does not explicitly state when not to use it, but given the tool's specificity and no similar siblings, this is sufficient.

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

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

Adds critical warnings beyond annotations: shared unauthenticated write surface, risk of data overwrite/wipe, requirement to surface the message. Annotations already indicate openWorldHint and non-read-only; description enriches with real-world implications.

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

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

Well-structured with front-loaded purpose, then usage, warning, alternative, and idempotency. Every sentence adds value; slightly verbose but acceptable.

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?

Single-parameter tool with output schema. Description covers all aspects: purpose, usage, warnings, ownership, idempotency, and alternative. No gaps given context.

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

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

Schema covers 100% of parameter description with app_id as UUID. Description adds no additional parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Make... PUBLIC' and the resource 'Charming app' with scope: anyone can read AND write shared data. It distinguishes from siblings like unset_public (reverse) and share_app (per-person access).

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

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

Explicitly provides when to use (totally-open surfaces like polls, RSVP lists) and when not (per-person access requires share with end-user role). Also notes idempotency and owner-only restriction.

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=false, openWorldHint=true), the description adds idempotency, that it returns the same URL without re-firing analytics when already remixable, and that anonymous apps cannot be made remixable. No contradictions.

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

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

The description is concise (4 sentences), front-loaded with the main action, and every sentence adds value. No unnecessary words.

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

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

Given one parameter, high schema coverage, and presence of an output schema, the description covers idempotency, prerequisites, and the core effect, making it complete for an agent to decide usage.

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

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

Schema coverage is 100% with a clear description for 'app_id'. The tool description does not add additional parameter-level details beyond the schema, so baseline 3 is appropriate.

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

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

The description explicitly states the action ('Mark a Charming app as remixable') and clarifies the effect: anyone opening the URL gets their own editable copy without mutating the original. This distinguishes it from siblings like 'unset_remixable' and '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 mentions a prerequisite (app must be claimed) and idempotency, but does not explicitly compare to alternatives like 'share_app' or 'set_public'. It gives context but lacks explicit when/not-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?

Beyond annotations (destructiveHint=true, readOnlyHint=false), the description details idempotency, length cap (2000 chars), automatic context appending, and the pitfall of hardcoded URLs pointing to the template. No contradictions 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 description is efficient and front-loaded, with every sentence adding unique value. It is slightly long but justified by the complexity; no redundancy.

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

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

For a mutation tool with destructive potential and specific rendering behavior, the description covers ownership, idempotency, length limits, clearing mechanism, and the automatic appending of app context. No gaps remain for an agent to infer.

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?

Even with 100% schema coverage, the description adds substantial value: explains the proper format for starter_prompt (generic instruction, not self-contained prompt), why not to embed URL, and how null/empty clears. This goes well beyond the schema's basic type info.

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

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

The description clearly states the tool's action ('Set or clear an app's authored starter prompt') and the specific resource (the app's starter prompt). It distinguishes this tool from general app mutation by focusing on the starter prompt, and the sibling tools include no direct competitor.

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

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

Provides explicit when-to-use ('frame a shared/remixable app's intended first action'), what-not-to-do ('do NOT embed the app's URL'), how to clear ('pass null or empty string'), ownership constraints ('owner-only; anonymous apps must be claimed first'), and idempotency. This covers all key usage decisions.

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

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

Discloses that the tool creates a PENDING invitation, describes each role's capabilities, clarifies that re-sharing without role leaves existing role untouched, and notes that no share role can share/delete/transfer the app. No annotations contradict; destructiveHint=true is consistent with role changes.

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 well-structured: starts with the main purpose, then details roles, invitation flow, and edge cases. Every sentence adds value, though could be slightly tighter. Front-loaded effectively.

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 three parameters, a rich output schema (implied), and many sibling tools, the description covers all relevant scenarios: pending invitations, role change behavior, account registration, and revocation. No gaps apparent.

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

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

Schema coverage is 100% (all parameters have descriptions). The description adds nuance: default role is 'collaborator', re-sharing without role leaves untouched, and invitee does not need a Charming account beforehand—adding value 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 starts with a clear verb ('Invite someone... OR change the role') and identifies the exact resource ('one of your apps'). It distinguishes from its sibling 'unshare_app' by mentioning revocation explicitly.

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

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

States when to use: 'Use this when the user wants to give a specific person access to an app, or to change what an existing collaborator/end-user/viewer can do.' Also explains when NOT to send a new invitation (re-sharing with role) and directs to 'unshare_app' for revocation.

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 mutation (readOnlyHint=false) and non-destructive nature. The description adds valuable behavioral context: source is server-enforced to 'agent', agents cannot impersonate, and ownership requirement, which are beyond annotation capabilities.

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, no filler, front-loaded with purpose, then constraints. 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 tool's complexity (5 params, nested objects, enum, output schema), the description covers purpose, usage, constraints, and parameter relationships sufficiently. The output schema exists, so return value details are not needed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by linking category 'crash' to crash_data requirement, and stating that at least one of text/structured_data/crash_data should be set. This goes beyond the schema's individual 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 uses a specific verb 'Record' and resource 'feedback about a Charming app', listing concrete use cases (bugs, enhancements, crashes, notes). It clearly distinguishes from sibling tools like list_feedback and other app mutation 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 states when to use (logging feedback) and provides constraints (source enforced to 'agent', caller must own app). It does not explicitly state when not to use or name alternatives, but the context is clear.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true), the description adds context: data retention, idempotency, and the requirement for login. 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 description is concise with three sentences. The first sentence immediately states the action, making it front-loaded. Every sentence adds value.

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

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

The description explains the tool's behavior, side effects (data retention), idempotency, and the effect on access. With an output schema present, this is complete for the tool's purpose.

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 the single parameter 100% with a clear description. The tool description does not add new parameter semantics, so a baseline 3 is appropriate.

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

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

The description clearly states the tool makes a public Charming app private, specifying the action and resource. It distinguishes from the sibling `set_public` by explicitly reversing its effect.

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

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

The description tells when to use the tool ('to close anonymous access') and describes the effect (visitors must log in). It also notes idempotency but does not explicitly mention when not to use it or alternatives.

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

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

Beyond annotations (destructiveHint=true), description reveals that existing remixes survive untouched and operation is idempotent. This adds critical behavioral context.

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

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

Three concise sentences, no wasted words. Key information front-loaded ('Stop allowing remixes'). Each sentence adds value.

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

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

Given single parameter, clear annotations, and output schema, the description fully covers what the tool does, its side effects, idempotency, and scope. No gaps.

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

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

Schema coverage is 100% with description 'The app ID (UUID) to stop sharing as remixable'. Tool description adds no additional parameter semantics beyond schema, earning baseline 3.

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

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

The description clearly states the action ('Stop allowing remixes') and resource ('Charming app'). It distinguishes from sibling set_remixable by specifying the inverse operation and noting idempotency.

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

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

Explicitly says 'Use this to turn off auto-forking for new visitors', providing context for when to use. Idempotency guidance encourages safe repeated calls. Sibling tool names give alternative for opposite 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?

The description discloses that the tool is destructive (consistent with annotation), idempotent, and takes effect immediately, adding beyond 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 concise sentences, front-loaded with the main action, no wasted words.

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

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

Given the presence of an output schema and annotations, the description fully covers behavior, idempotency, and effect timing, making it complete.

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

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

Schema coverage is 100% so baseline is 3. The description does not add significant meaning beyond the schema's parameter descriptions, though it clarifies idempotency.

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 (revoke another user's access) and the resource (one of your apps), and distinguishes it from sibling tools like share_app and delete_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 explains when to use this tool ('withdraw an invitation or remove a collaborator') but does not explicitly list when not to use it or name 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 indicate destructiveHint=true and readOnlyHint=false, which the description matches by stating the tool updates an app. It adds key behavioral details: synchronous execution (app is live on return), atomic edits with expected_version for concurrency control, and instruction to use shareUrl not url for sharing. No contradictions 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 description is well-structured with front-loaded purpose, clear sections for input shapes, and important notes at the end. While fairly long, every sentence adds value. Minor opportunity to trim redundant phrasing (e.g., 'Mutually exclusive' repeated).

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

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

Given the tool's complexity (7 parameters, two input shapes, concurrency), the description covers all key aspects: synchronous behavior, atomic edits, concurrency control, output field guidance (shareUrl vs url), and when to update description. It is fully actionable for an AI agent.

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

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

Schema description coverage is 100%, but the description goes far beyond by explaining the two input shapes in detail, including authoring rules for ui and module, the behavior of edits (exact string matching, replace_all), and the purpose of expected_version. This adds significant meaning beyond the schema.

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

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

The description clearly states 'Update an existing Charming app and render the fresh version inline.' It identifies the resource (Charming app), action (update), and ownership requirement (caller's own app, identified by UUID). It distinguishes from sibling tools like create_app and delete_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 explicit guidance on two mutually exclusive input shapes (full-source vs edits) and when to update the description. It contrasts with create_app by referencing its authoring rules. However, it does not explicitly list when not to use this tool versus alternatives like rename_app or set_public.

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

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

Discloses that server fetches remote file without bytes transiting through tool call, warns about MCP client stalls with large base64, and provides caps (10 MiB/asset, 50 assets/app, 100 MiB/app). Annotations are consistent (destructiveHint=true, readOnlyHint=false).

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 packed with information, front-loaded with purpose, then usage, then parameter details. No redundant or vague phrases.

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?

Fully covers all aspects: purpose, parameter selection, caps, how app reads asset, and capability requirement. Output schema exists, so return value explanation unnecessary.

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?

Despite 100% schema coverage, description adds critical meaning: parameter selection guidance (sourceUrl preferred over text/dataBase64), size limitations (sourceUrl docs, base64 <16KB), and default MIME type logic.

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 'UPLOAD A STATIC ASSET TO AN APP' with specific verb and resource. It distinguishes from sibling tools which all operate on apps rather than assets.

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

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

Explicitly states when to use ('when an app needs a large or static file') and provides clear parameter preference order (sourceUrl preferred, dataBase64 last resort) with warnings about stalls.

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