Charming

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

Annotations already provide idempotentHint=true and destructiveHint=false; the description adds that acknowledgment is durable and changes visibility in advisories and list_feedback_responses. This goes beyond the structured hints, although it does not describe the output shape or any side effects on the underlying feedback records.

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 statements are packed with relevant information: the action, the precondition, the effect on other tools, and the tool's durability/idempotence. No filler or redundant elaboration.

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 with a single well-described parameter and an existing output schema, this description covers what the tool does, when to use it, and what side effects to expect. An agent has enough context to call it appropriately.

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 fully documents the only parameter (response_ids as UUIDs returned by list_feedback_responses), and the tool description reinforces the purpose but does not add parameter-level detail. With 100% schema coverage, the baseline 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 specifies the action ('Acknowledge feedback responses'), its timing ('after the agent has processed them'), and its observable effect ('stop processed responses from appearing in advisories and list_feedback_responses'). It is easy to distinguish from sibling tools like list_feedback_responses or submit_feedback.

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 an agent when to call this tool ('after the agent has processed them') and what outcome to expect. It does not name alternative tools or edge cases, but the intended trigger and post-condition are clear enough for a competent agent.

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

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

The description adds side effects beyond annotations: 'leaves accepted desired source editable' and 'keeps the last active app running'. The idempotency statement ('Repeating cancellation returns the same terminal status') reinforces idempotentHint=true but adds detail. 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?

Two sentences, no filler. The primary purpose and key side effects are 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 the presence of an output schema and simple operation, the description covers the main behavior, idempotency, and side effects. It could detail error conditions or what happens to the build object, but for a cancel operation this is adequate. The description is complete enough for an agent to use 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?

Only one parameter (build_id) is present, and the schema description ('Build ID returned by create_app or update_app') already provides full coverage. The description does not add further semantic nuance about the parameter, but with 100% schema coverage, the baseline of 3 applies.

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

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

The description clearly states the verb 'cancel' and the resource 'accepted app build', and adds the condition 'before it publishes'. This distinguishes it from delete_app (which removes the app) and get_app_build (which retrieves). The scope is precise and actionable.

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

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

It explicitly states when to use it ('accepted app build before it publishes') and implies that once published or not accepted, this tool is inappropriate. It does not name alternatives, but the context is strong enough to route an agent. Could improve by explicitly saying when not to use (e.g., for deleting the app).

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 significant behavioral details: reusing a manifest.id the caller owns replaces the existing app module/UI/styles in place; idempotency_key enables background builds with a buildId to poll; the shareUrl field is user-facing while the url field embeds a write-capable token. It also documents storage semantics, capability declarations, and failure modes (e.g., localStorage silently vanishes). The destructiveHint annotation is consistent with the described replacement behavior, with no contradiction.

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

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

The description is exceptionally long and dense, but nearly every sentence carries a rule or operational constraint necessary for this tool's dual-contract complexity. It is well front-loaded with the core purpose and key side-effect warnings. It loses one point because it duplicates some content that already lives in the rich parameter docs and could be tightened without losing meaning.

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—two authoring contracts, background builds, destructive replace semantics, capability declarations, storage constraints, and a machine-only URL security warning—the description is remarkably complete. The presence of an output schema reduces the need to explain return values, and the description still covers the critical result fields (buildId, shareUrl). Nothing an agent needs to call this tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds substantial operational meaning: idempotency_key is tied to background builds and retries, expected_revision is required for reuse of an existing manifest.id, team_id is owner/admin-gated, and the module/ui/description params carry distinct authoring contracts. The description also explains result semantics (shareUrl vs url) that are not in the schema. It goes far beyond merely restating parameter names.

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

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

The description opens with a specific verb and resource: 'Create a new interactive web app and render it inline. Use this to build a new app from a request.' It immediately distinguishes itself from the sibling update_app by saying 'use update_app to edit a known app ID by UUID,' and it clarifies the existing-contract vs ESM contract behavior. An agent can confidently select this tool for new-app creation rather than mutation or query 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 gives explicit when-to-use guidance: build a new app from a request, with a clear alternative for edits (update_app). It also handles unsupported requests explicitly: 'do not fake support. Build the closest local-state version, then log the gap with submit_feedback.' It points to read_docs for full documentation and to the charming:app-guide prompt for canonical examples. This is exemplary routing and exclusion guidance.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description correctly implies a write operation without destruction. It adds valuable behavioral context: the target op is invoked with empty input, duplicate Routines are rejected, and there are hard caps (3 per app, 25 per user). This goes beyond the structured annotations and helps the agent anticipate side effects and failure conditions.

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, two sentences, and front-loads the primary use case before detailing constraints. Every sentence contributes: the first defines the scenario, the second explains mechanics, input requirements, and limits. There is no filler or redundancy.

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

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

The tool has an output schema (indicated by 'Has output schema: true'), so return values are covered there. The description covers the key aspects an agent needs: when to use, allowed intervals, the empty-input requirement, duplicate rejection, and caps. For a creation tool with clear schema and annotations, this is complete.

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

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

Schema coverage is 100%, so each parameter (app_id, op, interval) is already described. The description adds meaning by clarifying that interval accepts only 'hourly', 'daily', or 'weekly' and explicitly rules out cron syntax. It also explains that the op is called with empty input, which informs the agent that op must not have required fields—a semantic detail not present in the schema.

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

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

The description clearly states the tool creates a Routine that schedules an app op on a timer, and distinguishes it from chat-based operations. It specifies the verb 'schedules' and the resource (an app's declared op), and the opening phrase 'Use this when the user wants an app op to run on its own, on a timer' immediately clarifies the primary use case, setting it apart from siblings like update_routine or delete_routine.

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

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

The description gives a clear trigger condition ('when the user wants an app op to run on its own, on a timer') and explicitly notes it is not a chat operation. It also states constraints like 'no cron syntax' and that the op must not have required input fields, which guides correct usage. However, it does not explicitly mention when to use an alternative tool (e.g., update_routine to modify an existing Routine), though this is 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?

Goes well beyond the destructiveHint annotation by spelling out irreversibility, the host-side confirmation prompt, and the fail-closed behavior that requires confirm: true when the prompt is unavailable. This gives the agent a complete picture of side effects and safeguards.

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 tight sentences, front-loaded with the core action, then the conditional nuance. No redundant filler; every clause carries 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 the action, ownership constraint, optional data purge, irreversibility, and confirmation edge-case behavior. With a full input schema and clear sibling distinctions, nothing essential is missing for an agent to invoke it correctly.

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

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

Input schema already covers all three parameters at 100% coverage; the description adds real value for confirm by explaining the fail-closed fallback semantics. It does not deepen app_id or purge_storage much beyond the schema, but the confirm addition justifies a strong score.

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

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

The description opens with a specific verb and resource ('Permanently delete a Charming app the caller owns'), adds the optional purge-storage nuance, and clearly distinguishes this from siblings like update_app or delete_routine. No ambiguity about what the tool does.

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?

'Use this to remove an app the caller no longer wants' gives a clear call-context, and the ownership condition further scopes when it applies. It does not explicitly name alternatives or say when not to use it, 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 already declare destructiveHint=true and readOnlyHint=false, which signal this is a mutation that destroys data. The description aligns with these traits by saying 'stop and remove,' but it adds no extra behavioral context such as irreversibility, required permissions, or consequences beyond what annotations already convey. With annotations covering the primary behavioral flags, the description provides minimal additional value.

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, directly stating the tool's purpose. It is concise and front-loaded, though it could be slightly more precise by explicitly using 'delete' instead of 'stop and remove.' Still, it is efficient and 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 delete tool with one well-documented parameter and annotations indicating destructive behavior, the description is largely complete. An output schema exists, so return values need not be described. It lacks mention of edge cases (e.g., whether deleting a nonexistent routine errors), but these are not critical for basic usage. Overall, it meets the needs of an agent selecting and invoking 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 input schema fully describes the single required parameter, including its format ('routine_<uuid>') and meaning. Since schema coverage is 100%, the description does not need to add parameter details. The description contributes nothing 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 uses a specific verb ('stop and remove') and names the resource ('Routine'), which clearly identifies the action. It distinguishes itself from sibling tools like 'create_routine' and 'update_routine' by implying deletion, though 'delete' is not explicitly used. The phrasing is slightly indirect but still 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 the tool is for stopping and removing a Routine, giving a clear general use case. However, it provides no explicit guidance on when not to use it or how it compares to alternatives (e.g., whether updating is preferred over deletion in certain contexts). The usage is implied but not detailed.

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

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

Annotations already declare readOnly/destructive/openWorld, but the description goes well beyond them: it discloses that the response contains a live embedded UI plus callable API operations, and warns that the `url` field is machine-only and embeds a write-capable access token while `shareUrl` is the user-safe one. That token-handling caveat is a meaningful behavioral disclosure not available anywhere in structured fields.

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?

Front-loaded with the core action, and every subsequent sentence carries routing or safety information rather than filler. It is dense but slightly long, packing five distinct ideas into one paragraph where minor trimming would still preserve meaning.

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?

Although an output schema exists, the description still tells the agent what comes back (embedded UI plus invokable operations) and which return field is safe to hand to a user versus which is token-bearing. For a render tool with a downstream query/mutate workflow, nothing an agent needs to call it correctly is missing.

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

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

There is a single parameter with 100% schema description coverage, so the schema fully documents app_id including its UUID format and pattern. The description's 'by ID' adds no format or constraint detail beyond that, 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 and resource ('Fetch an existing app by ID and render it inline') and immediately distinguishes itself from the closest sibling by contrasting rendering against list_apps' metadata-only return. An agent can tell exactly what this does and what it is not.

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

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

Gives explicit when-to-use ('open, re-render, or continue working with an app the caller already has'), names the prerequisite alternative ('call list_apps first to find the ID'), and points to the downstream alternatives query_app and mutate_app with their read/write split.

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 meaningful behavioral context beyond the readOnlyHint annotation by stating the operation is non-running/non-publishing and that status persists after authoring access is removed. This clarifies side-effect-free inspection and historical availability, though it does not address auth or rate limits.

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

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

Three short sentences, front-loaded with the primary purposeaint, then the include_source guidance, then the persistence guarantee. No filler or repetition.

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 a full output schema and complete parameter descriptions, the description covers the key operational context: accepted build inspection, no run/publish side effects, source recovery, and availability after authoring access removal. Minor ambiguity with get_app/get_app_source remains unaddressed.

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

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

Schema coverage is 100% and the description only restates the include_source purpose ('recover the exact submitted source') that the schema already conveys. The description adds little semantic value beyond what the parameter 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?

The description clearly identifies the operation as inspecting an accepted app build without running or publishing it, which is specific and distinct from generic retrieval. It does not explicitly contrast with sibling tools like get_app or get_app_source, so it stops short of full differentiation.

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

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

The description gives clear context for when to use the tool ('inspect an accepted app build') and explicitly instructs using include_source to recover the exact submitted source. It does not name alternatives or state when not to use it, but the usage scenario is well defined.

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, so the safe-read profile is conveyed. The description adds value beyond that by disclosing that the result includes a revision token intended for optimistic-concurrency edits and by naming the next-step integration with update_app. Failure/auth behavior is missing, but it is a minor complete a minor gap given annotations and output 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 short sentences, each earning its place: first defines the exact return current revision, second gives the downstream update_app instruction, third states the when-to-use context. No filler or repeated annotation.

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 read tool with a known output schema, this description covers the return contents, the purpose of the revision, the downstream update call, and the caller-ownership condition. Failure/error behavior (e.g., invalid app_id or non-owned app) is omitted, but calling the tool correctly does not require that.

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

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

Schema description coverage is 100%: the sole required app_id is already fully documented as a UUID in the schema. The description contributes fewer intro fields names (e.g., module, ui script, styles, revision) to provide context, but does not add per-parameter syntax or constraints. With high schema coverage, 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's verb 'Return' and resource specification is precise: 'raw persisted source (module, frontend ui script, and styles)' plus 'current revision for optimistic-concurrency edits.' It further distinguishes this tool from siblings by naming the downstream consumer (update_app) and use cases (inspect, debug, edit), so no other schema or description is needed to tell it apart.

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

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

It explicitly states when to use this tool: 'Use this when you require the source to inspect, debug, or edit an app the caller owns.' It also gives concrete downstream instruction by having the returned revision passed into update_app's expected_revision. It does not enumerate alternative tools or when not to use it, but the context is clear and actionable.

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?

Rich behavioral detail beyond readOnlyHint: includes owned+shared scoping, role semantics (collaborator/end-user/viewer), read-only share convention, url vs shareUrl distinction, and forward-compat note on description. This goes well beyond a generic 'list' description.

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?

Front-loaded with core behavior and guidance on when to call it/newline; very detailed but each sentence adds information. Slightly long and field-heavy, but 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?

Since there is no output schema, the description compensates by enumerating the returned fields and their semantics and tells the agent how to use the result (capabilities for integration, shareUrl for sharing). Missing explicit error scenarios or permission boundaries, but strong overall.

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

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

Schema coverage is high (limit is described with max and default). The description adds meaningful cross-field guidance: cursor-based pagination uses the prior call's nextCursor, which clarifies a relationship not inferable from the parameter list alone.

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

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

Begins with a specific verb and resource: 'List the caller's Charming apps — owned plus shared.' It clearly defines the scope (owned and shared, with view-only shared items noted) and states the primary use case (finding an app's id before fetch/edit/call). This is unambiguous and distinct from sibling tools like get_app or get_app_source.

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 instructs agents to use this to get an app's ID before fetching, editing, or calling itaine — a clear decision rule. It also implies the cross-tool benefit of capabilities.exports for discovering callable operations without separately using other toolsaint list_app_shares or get_app_source. However, it doesn't explicitly state when NOT to use this tool vs. siblings.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false. The description goes further by defining the three status values and three role semantics, which materially shapes expectations about what the tool returns. This is exactly the kind of behavioral detail that helps an agent interpret output correctly.

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

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

Every clause earns its place: it gives the tool's purpose and then compactly explains each status and role value, all in one sentence without repetition.

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

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

For a simple read-only listing tool with a single UUID parameter, the description fully covers the operation, the return categories, and the meaning of each label. The output schema would provide the structural details, so no major information gap exists.

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

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

Schema coverage is 100% and app_id is adequately documented as a UUID in the schema. The description does not add new parameter-level semantics, but it doesn't need to; 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?

States a specific verb ('see who an app is shared with') and a specific resource (an app's shares), then details exactly what is listed. The status and role labels make the tool's purpose unmistakable and distinct from sibling tools like get_app or share/unshare operations.

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

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

Opens with 'Use this to see who an app is shared with', giving a clear trigger condition. It does not name alternatives or exclusions, but the purpose is specific enough that an agent can select it without confusion.

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 provide readOnlyHint=true and destructiveHint=false, and the description adds valuable behavior beyond that: owner-checked access, scope broadening when app_id is omitted, ordering (newest first), and cursor-based pagination. This gives the agent a concrete picture of the tool's behavior without contradicting the annotations.

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

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

The description is three sentences and each one earns its place: statement of purpose, usage guidance, and behavior/pagination details. It is front-loaded with the main verb and resource, and avoids unnecessary flourishes. It could be shortened slightly by merging the first two sentences, but it is still appropriately sized.

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 an output schema present and 5 parameters all documented in the input schema, the description's job is mainly to add scope, pagination, and ordering, which it does. It fully covers the owner-checked behavior and how pagination works with cursor. It doesn't discuss filtering capabilities like since or category, but those are already in the schema, so no meaningful gap remains.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only a little meaning beyond the schema: it reframes app_id's owner-scoping in prose and implicitly communicates cursor usage, but the schema already explains each parameter in similar terms. No substantial extra semantics are added for limit, since, or category.

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 feedback rows') and clarifies that it targets the caller's apps, which is clear and distinct enough. It does not explicitly distinguish itself from sibling tools like list_feedback_responses or acknowledge_feedback_responses, but the focus on 'feedback rows' plus the caller scope communicates the purpose effectively.

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

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

It gives clear when-to-use guidance: 'Use this to review feedback previously recorded for an app.' It also explains the two major usage modes (with app_id vs. without), giving users the key behavioral switch without needing to read the schema. It does not name alternatives or explicitly say when not to use it, so it stops short of a 5.

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

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

Annotations already mark readOnlyHint=true, but the description adds meaningful behavioral context: responses are unread, ordered oldest-first, and reading does not acknowledge them. The note that acknowledge_feedback_responses must be called separately prevents a common misuse, going well beyond structured annotation data.

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 tightly scoped sentences deliver the core purpose, usage trigger, ordering, non-acknowledgment behavior, and follow-up instruction with no filler. Key operational facts are 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?

With a full output schema, 100% parameter schema coverage, and annotations carrying safety semantics, everything an agent needs is present: when to call, what it returns semantically, ordering, and post-processing action. Nothing important is left to inference.

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 description coverage is 100%, so the schema already documents limit and cursor. The description adds context on response ordering and the acknowledgment follow-up, but no additional parameter-level 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 uses a specific verb ('Fetch') and resource ('unread Charming staff responses to feedback'), clearly distinguishing this read tool from the sibling acknowledge_feedback_responses. It also conveys the unique unread/acknowledgment semantics that separate it from other feedback tooling.

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 tells the agent when to use the tool ('when a feedback-responses-available advisory appears') and instructs the follow-up action of calling acknowledge_feedback_responses after processing. This gives clear, decisive routing guidance relative to its sibling 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 declare readOnlyHint=true and destructiveHint=false, so the description only adds caller scope and cross-app aggregation. It does not describe pagination, sorting, or other behavior, but for a simple read-only list with an output schema this is acceptable. No contradiction 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?

A single sentence with no filler, front-loading the action and scope. Every word 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 parameterless read-only listing tool with annotations and an output schema, the description covers the essential semantic scoping (caller, across apps). It is complete enough, though it does not explicitly discuss output contents or alternative 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 tool has zero parameters and schema coverage is effectively complete; there is nothing for the description to add. The baseline for zero-parameter tools is 4.

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

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

The description states a specific verb ('see') and resource ('caller's Routines across their apps'), making the tool's purpose clear. It is distinguishable from list_apps by targeting routines, though it does not explicitly name sibling alternatives.

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 directly tells the agent when to use it ('Use this to see...'), but it does not provide guidance on alternatives or exclusions. Usage context is implied rather than fully explicit.

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

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

Annotations already flag readOnlyHint=false and destructiveHint=true; the description adds useful nuance by covering operations whose read/write safety cannot be determined, stating that it returns the operation result, and clarifying that it does not edit code. No contradictions 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 sentences: the primary action, the selection rule for when to use it, and the disambiguation fallback via get_app. Front-loaded and without redundant schema repetition.

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

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

The description fully resolves the key agent decision—when to choose this tool over query_app and how to resolve unknown operations via get_app. With an output schema present and only three parameters, no further information is 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 parameters are already fully described. The description reinforces that op is an operation name and that params are part of the operation, but it doesn't add much 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 and object: 'Run a mutating backend operation on a Charming app and return its result, without editing code.' It is immediately distinguishable from read-only siblings, and it tells the agent that this tool is for state-changing work rather than source editing.

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 directs agents to use this tool for state-changing operations, including ambiguous ones, and to use query_app for read-only operations. It also tells agents to call get_app when the operation or tool is unknown, covering the main routing ambiguity.

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 readOnlyHint and destructiveHint annotations already communicate the safe, read-only nature, and the description reinforces this with 'read-only' and 'without editing code.' However, the description does not add much beyond the annotations, such as auth requirements, error behavior, or rate limits.

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

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

The description is compact and front-loaded: the core purpose and read-only constraint appear in the first sentence. The following sentences give essential routing guidance without filler or repetition.

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 an output schema present, the description does not need to explain return values. The description, annotations, and schema together provide everything an agent needs to select the tool, invoke it, and recover from uncertainty about operation names.

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 input schema fully documents app_id, op, and params. The description adds minimal parameter-level meaning beyond saying operations are routed and that get_app lists available operations, which is useful context but not required for parameter understanding.

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

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

The description states a specific action ('Run a read-only backend operation'), a clear resource ('a Charming app'), and the result ('return its result'). It also explicitly distinguishes itself from mutate_app, making the purpose unmistakable.

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

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

The description gives clear when-to-use guidance: use this tool for read-only state operations. It explicitly names mutate_app for state-changing operations and get_app as the fallback when the operation name or required tool is unknown. This fully covers selection among siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral details beyond annotations: pagination via offset (chunks of up to 20,000 characters), default to llms.txt when path is omitted, acceptance of paths without .md, rejection of URLs/query strings/fragments, and rate limiting. No contradiction 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?

The description is structured efficiently: it starts with the primary purpose and usage flow, then goes into when to use it, return format, limitations, and alternatives. Every sentence adds critical information—no filler. Information is front-loaded so an agent quickly grasps how to call it correctly.

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 (read-only, 2 params, output schema exists), the description is fully complete. It covers the invocation flow, pagination mechanics, accepted inputs, exclusions, and rate limits. With annotations covering safety and an output schema handling return values, nothing an agent needs is missing.

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

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

Schema description coverage is 100% and the schema itself provides detailed descriptions for both 'path' and 'offset'. The description adds valuable semantics: the default path when omitted (llms.txt), that a 'docs/' prefix is accepted, that slugs without .md work, and that offset should be taken from prior next_offset. This goes beyond the schema, though the schema already covers the basics, so it earns a 4 rather than 5.

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 ('Read') and resource ('Charming documentation') with a clear scope: 'without web access'. It also mentions the intended use cases ('building an app or looking up the runtime, API, or capability reference'), which differentiates it from all sibling tools—no other tool reads documentation. This 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?

It provides explicit usage guidance: call without arguments to get the index, then pass a page path from that index. It names an alternative for a specific need ('For the full authoring reference, use llms-full.txt'), implying when not to use this tool. It also states limitations like 'Only public Charming docs can be read' and 'Limited to 60 reads per caller per minute', giving clear boundaries.

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, the description explains that renaming changes the public URL, old URLs redirect, and the url field is machine-only with a write-capable token (a serious security-relevant behavioral note). It also implies a mutating operation without destructive side effects, consistent with readOnlyHint=false and destructiveHint=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?

The description is slightly long, but each sentence contributes meaningful information: identity distinction, redirect behavior, slug rules, and security guidance. The key usage guidance is front-loaded before the slug validation rules.

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 output schema, it fully covers the operation's semantics, parameter meaning, security-relevant urn field warning, and redirect behavior. It even teaches the safe way to share URLs, which closes the loop on how an agent should use the result.

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 both parameters with 100% coverage, including slug constraints and lowercasing/trimming. The description adds semantic value by contrasting the slug with title/displayName and machine id, and ties the result's shareUrl to usage guidance.

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 specific 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 text gives direct guidance: it contrasts this tool with update_app by stating that editing the title via update_app does not change the slug, while this tool does. It also specifies the context (giving an app a different public URL) and the fact that the old URL redirects, so an agent can choose correctly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this by explicitly stating the copy URL 'starts browser navigation... it is not an MCP or REST write.' This preempts a likely misreading of the copy URL as a write-capable endpoint.

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 longer than average but each sentence earns its place: purpose, usage context, return values, the critical browser-copy caveat, and the follow-up workflow. It is front-loaded with the main action and well organized, though slightly dense.

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 an output schema present, return-value details are already structured, and the description still adds the essential browser-navigation caveat and the post-copy discovery flow. The tool is fully specified for an agent to select and 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 description coverage is 100%, so all three parameters are already documented. The description adds high-level purpose ('search by keyword') but does not add substantive parameter-level meaning beyond the 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?

States a specific verb and resource: 'Search the public Charming Template directory by keyword.' It further differentiates from siblings by explicitly positioning it as the pre-create_app check and as the answer to 'what Templates exist,' which separates it from list_apps and create_app.

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

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

Gives explicit when-to-use guidance: before calling create_app, or when the user asks what Templates exist. It also explains the post-copy workflow with list_apps and get_app_source, effectively telling the agent which sibling tools to use after the browser flow.

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, the description discloses that URLs change, the old handle redirects so existing links remain valid, the tool is scoped to the signed-in user, reserved words may apply, and there is a rolling 30-day rate limit. This gives the agent substantial behavioral context that structured annotations do not convey.

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

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

The description is focused and front-loads the key purpose before adding constraints, but it is somewhat dense and repeats the validation rules already present in the schema. Still, each sentence contributes a distinct fact, so the length is justified.

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

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

Given the simple one-parameter schema, the output schema, and annotations, the description is sufficiently complete: it covers scope, semantics, constraints, side effects, and limits. An agent can call this tool correctly without needing additional edge-case 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 handle validation and trimming at 100%, so high schema coverage raises the baseline. The description still adds meaning beyond the schema by tying the parameter to the user's app URLs and mentioning reserved words and the rate limit, which affect how the handle value should be chosen.

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

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

The description names a specific verb and resource: changing the signed-in user's handle, and explains what a handle is and how it affects app URLs. It clearly differentiates this from sibling set_* and rename-style tools by scoping it to the current user and handle specifically.

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?

"Use this to give the current user a different handle" is an explicit usage statement, and the description adds that it acts on the current signed-in user with no user id. It provides clear context and exclusions, though it does not name alternative tools or give a when-not case beyond the current-user scope.

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, it discloses that the operation is idempotent and does not re-fire analytics, that only the owner can perform it, and that anonymous apps must be claimed first. It also explains the read-only nature of the public viewer, which is critical side-effect information 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?

The most important behavior is stated first, and every subsequent sentence adds a distinct operational fact: use case, write-access alternative, separate settings, idempotency, and owner prerequisite. 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 one-parameter tool with an output schema, the description is fully sufficient. It covers prerequisites, side effects, idempotency, use case, and how to interpret the result, leaving no important context for the 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?

The single parameter app_id is already fully described by the schema, so the description adds no extra parameter-level meaning. The 100% schema coverage makes the baseline score of 3 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 uses a specific verb phrase ('Make a Charming app Public') and clearly defines the outcome: anyone with the URL can open the app in the viewer without login, but visitors cannot modify data. It is immediately distinguishable from the sibling mutation and sharing 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?

It explicitly states when to use this tool (read-only public surface) and when not to (write access should use sharing with the end-user role or the signed-in audience option). It also separates Template and Listed settings, so an agent can rule out alternatives without opening other schemas.

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 goes well beyond what annotations provide by disclosing that the original is never mutated, listing metadata and Listed state are untouched, each copy belongs to the signed-in visitor from creation, and the call is idempotent with no analytics refire on repeat calls. The deprecated-alias and metadata-blind traits are also important non-obvious 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?

The description is longer than minimal but every clause earns its place: deprecation, replacement, input contract, side effects, ownership, idempotence, and the anonymous-app constraint. It is front-loaded with the most critical routing decision (deprecated, use `set_template`) and then flows into details without repetition.

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, deprecated alias tool with an output schema, the description covers selection guidance, behavioral side effects, idempotence, ownership, and a failure condition (anonymous apps). An agent has enough information to decide whether to call it and what will happen when it does.

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 fully documents `app_id` as a UUID, and the description reinforces that this deprecated alias accepts only that single parameter. It adds semantic meaning beyond the schema by clarifying that the parameter is the only input and that the app must have been claimed, which helps avoid misuse.

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 this is a deprecated alias for `set_template`, taking only `app_id` and enabling Template for readers of the source App while leaving listing metadata unchanged. It names the replacement sibling tool, making the tool's place among `set_template`, `unset_remixable`, and `share_app` immediately understandable.

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

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

It gives an explicit when-to-use rule: use this only when an older workflow requires the deprecated alias, and use `set_template` for new work. It also adds a hard prerequisite—anonymous apps must be claimed first—which is exactly the kind of usage constraint an agent needs before selecting the tool.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, and destructiveHint=true, but the description adds substantial behavioral context beyond those flags: it explains the automatic appending of name/description/URL/access token at render time, the idempotency (re-setting same value is a no-op), the length cap, and the owner-only requirement. It also clarifies that clearing reverts to the generic default. This is rich behavioral disclosure that goes well beyond the annotations.

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

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

The description is dense but well-organized, front-loading the core purpose and then covering constraints, clearing behavior, ownership, idempotency, and length cap. Every sentence earns its place, though it is somewhat long. The structure is logical: purpose, usage guidance, anti-pattern warning, clearing semantics, access control, idempotency, and limit. Slightly verbose but not wasteful.

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 (mutation with ownership constraints, clearing semantics, and a critical anti-pattern about URLs), the description covers everything an agent needs to call it correctly: what to write, what to avoid, how to clear, who can call it, and the length limit. The output schema exists, so return values don't need explanation. The sibling list shows many app-related tools, and this description clearly distinguishes set_starter_prompt from them.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds value by explaining the render-time auto-append behavior and the 'do NOT embed URL' rule, which directly informs how to fill starter_prompt. It also clarifies the null/empty-string clearing semantics. The only minor gap is that app_id semantics are fully covered by the schema, so the description doesn't add much there, but the starter_prompt guidance is strong.

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 ('Set or clear') and resource ('an app's authored starter prompt'), and explains the exact purpose: prefilling a getting-started instruction in the chat host when a visitor clicks 'Open in Claude' or 'Open in ChatGPT'. It clearly distinguishes this from generic app updates by focusing on the starter prompt behavior and even contrasts it with the generic default. This is unambiguous and differentiates the tool from siblings like update_app or mutate_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 explicit when-to-use guidance: 'Use this to frame a shared/remixable app's intended first action for visitors.' It also provides clear exclusions and constraints: do NOT embed the app's URL, write a generic instruction, pass null/empty string to clear, owner-only, anonymous apps must be claimed first, and idempotent behavior. This is comprehensive and leaves little 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 the annotations, the description discloses unique behavioral traits: the difference between 'listed' and live access, that each copy belongs to the signed-in visitor, idempotency, and odd patch semantics for `listed` omission. It adds valuable behavioral context entirely absent from the schema/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 wordy but each sentence carries a distinct, non-redundant idea—purpose, access scope, usage, ownership, patch behavior, listing requirements, idempotency, anonymous restriction. It is front-loaded with the primary purpose and maintains a logical left-to-right order that maximizes 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?

For a tool that both mutates a property and has optional performance community pages, the definition gives all necessary : use cases, side effects, parameter behavior, validation constraints, and an edge case ('Anonymous apps cannot be made into templates'). Output schema being present, no return-value description is missing.

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

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

While schema coverage is 100%, the description enriches parameter understanding with patch semantics ('change only when supplied'), the nonblank title/summary prerequisite for listing, alt text and asset-key validation for images, and the non-reset behavior of omitting `listed`. These constraints are cross-field and not captured by per-parameter 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 first sentence names the verb ('Enable') and resource ('Charming Template'), and immediately distinguishes the tool from siblings by noting it is 'not access to the live App or its data'. This clear separation from set_public, share_app, or search_templates is self-evident.

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 the 'when' in the second sentence: 'Use this when the user wants independent copies or a public Template listing, not access to the live App.' It also supplies a prerequisite and excludes anonymous apps, giving a clear decision boundary between this and the 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?

Even though annotations already mark the operation as writing and non-read-only, the description adds essential behavioral context: invitations are pending until the invitee accepts, re-sharing with a role updates the existing grant in place, re-sharing without a role preserves the role, and unknown handles error because no address exists. This goes well beyond the annotations and makes side effects predictable.

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 and well-ordered: purpose first, then lifecycle, roles, re-sharing semantics, limitations, and revocation. Almost every sentence adds distinct information, though a slightly shorter structure with role descriptions separated from edge cases would improve scannability.

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 three parameters, an output schema, and meaningful behavioral edge cases, the description is complete. It covers the pending grant, account eligibility, role changes, re-sharing behavior, no-account invites, unknown-handle errors, and the revocation path. An agent has enough information to call the tool correctly in nearly all realistic scenarios.

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

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

Schema coverage is 100%, but the description enriches all three parameters: it explains the role enum with concrete capability differences, clarifies that `collaborator` is the default, and details how `grantee` can be a handle or email, including the no-account signup path and unknown-handle failure. This materially exceeds what the schema alone 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 opens with a specific verb and resource: 'Invite someone to one of your apps, OR change the role of someone you already invited.' It clearly distinguishes the tool from siblings by naming the close alternative `unshare_app` and by framing the action around access grants rather than app creation or mutation.

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

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

It explicitly states when to use the tool: 'Use 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.' It also names the complementary operation (`Revoke anytime with unshare_app`) and explains the pending-invitation behavior, giving an agent clear selection criteria.

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 indicate non-read-only and non-destructive behavior. The description adds meaningful behavioral constraints beyond the annotations: source is server-enforced to 'agent', impersonation of user or auto-crash sources is not possible, and app:run permission is required.

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 with the main purpose, followed by behavioral constraints. The first two sentences are slightly redundant ('Record' vs. 'Use this to log...'), but no unnecessary detail is included.

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 parameter details and annotations cover read/write traits, the description adds the crucial server-enforcement and permission context. It doesn't describe response semantics, but the output schema likely covers that; overall it is sufficiently complete for an agent.

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

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

The input schema already provides full descriptions for all parameters, including category enum values and crash_data requirements. The description does not add additional parameter-level meaning, 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 clearly states the verb ('record'), the resource ('agent-authored feedback about a Charming app'), and the scope (bugs, enhancements, crash reports, qualitative notes). This is specific enough to distinguish it from sibling tools like list_feedback or acknowledge_feedback_responses.

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 says when to use the tool ('Use this to log observed bugs, suggested enhancements, caught crash reports, or qualitative notes') and adds the constraint that callers must have app:run access. It does not mention explicit exclusions or 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 the annotations (destructiveHint=true, readOnlyHint=false), the description adds crucial behavior: anonymous visitor data is retained, the app URL now requires login, and idempotency. These details give an agent a clear picture of the side effects without needing to infer them from the annotation flags.

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 with zero filler. The primary purpose is stated first, followed by the behavioral consequence for visitors and data, and finally the idempotency note. Every sentence earns its place and the text is easy to scan.

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

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

For a single-parameter, well-annotated mutation with an output schema, the description covers the key aspects an agent needs: what changes, who is affected, what remains, and edge-case idempotency. There is no obvious missing information that would prevent correct invocation.

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

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

The schema already covers the single parameter app_id with a description and strong validation. The tool description does not add anything new about the parameter itself—it just reflects the same usage. With 100% schema coverage, the baseline is 3, and the description provides no additional semantic value.

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

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

The description clearly states a specific action: making a public Charming app private again. It differentiates itself from siblings like set_public (the inverse) by explicitly explaining the effect on anonymous access and login requirements, leaving no ambiguity about what the tool does.

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 specifies the exact use case: to close anonymous access and require login. It also notes the idempotent no-op behavior on already-private apps. However, it does not explicitly compare to sibling tools like set_public or unset_remixable to state when NOT to use this one, so it falls just short of a 5.

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

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

Annotations only indicate readOnly=false and destructive=true; the description adds crucial non-obvious behavior: existing copies survive untouched, a public template listing is cleared because listed apps must stay copyable, and the operation is idempotent. These warnings go beyond the annotations and help the agent reason about side effects.

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

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

The description is compact and front-loaded with the most important guidance: deprecation and the preferred alternative. Each sentence adds distinct value—effect, side effects, and idempotency—without redundancy. This is an exemplary concise 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?

Given the annotations already flag destructive behavior, the description supplies the missing operational details: existing copies survive, template listing is cleared, and repeated calls are harmless. It also names the successor tool, making the overall context complete for an agent deciding whether and how to call 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?

The input schema already fully documents `app_id` as a required UUID with 100% coverage, so the description has little parameter meaning to add. It only refers to 'a Charming app' implicitly through the tool semantics. This is acceptable baseline behavior when the schema carries the 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 names a specific action—'Stop allowing remixes of a Charming app'—and immediately clarifies that this tool is deprecated in favor of `unset_template` with an identical effect. It also spells out what the tool does: stop offering copies to new visitors, keep existing copies, and clear any public template listing. This leaves no ambiguity about the tool's role among its many sibling template/remix 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 first sentence gives direct routing guidance: 'Deprecated: use `unset_template` instead (identical effect).' It then specifies when this operation applies ('stop offering copies to new visitors') and notes that an already-non-remixable app can be safely targeted due to idempotency. This is sufficient usage guidance for a single-parameter 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?

The description adds meaningful behavioral context beyond the annotations: it explains that existing copies survive untouched, that the operation is idempotent, and that calling it on an app that is neither copyable nor listed is a no-op. This is valuable transparency for a destructive operation. The annotations already declare destructiveHint=true, and the description does not contradict that.

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 purpose, the second clarifies the scope, and the third explains idempotency. Every sentence earns its place with no wasted words.

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

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

For a single-parameter tool with a full schema and an output schema, the description covers the essential behavioral aspects: what is turned off, what survives, and the no-op case. It could arguably mention the output/return value, but the presence of an output schema reduces that burden. The description is complete enough for an agent to 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 already provides 100% coverage for the single parameter, app_id, with a clear description ('The app ID (UUID) to stop publishing as a template'). The description does not add additional parameter-level detail, but with full schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the verb ('Stop treating'), the resource ('a Charming app'), and the effect ('turn off copying for new visitors and clear any public listing'). It also distinguishes itself from related operations by noting that existing copies survive untouched, which helps an agent understand what this tool does and does not do.

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 for when to use this tool: when you want to stop treating an app as a template. It also notes the idempotent behavior, which is useful guidance. However, it does not explicitly name sibling alternatives like set_template or unset_public, so the when-not-to-use guidance is implied rather than explicit.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the mutating and destructive nature is known. The description goes further by disclosing that effects take effect immediately for new requests and that the operation is idempotent (revoking a non-existent grant is a no-op). These details are not in the annotations or schema, adding genuine behavioral context that helps the agent anticipate outcomes.

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

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

The description is three sentences, tightly packed with purpose, usage, and behavior. It front-loads the primary function, then the usage condition, then the two key behavioral traits (immediacy and idempotency). No wasted words or redundant phrasing.

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

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

For a simple two-parameter tool with an existing output schema, the description covers all necessary aspects: what it does, when to use it, how it behaves, and edge cases (idempotency). Combined with the annotations and schema, an agent has everything needed to call it correctly and interpret results.

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 app_id and grantee are documented in the schema. The description adds context about app ownership ('one of your apps') that is not present in the schema's parameter description, clarifying that the app must belong to the caller. This goes beyond the schema and adds value, though it does not elaborate on grantee specifics beyond what the schema already states.

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: revoking another user's access to an app. It explicitly distinguishes between revoking a pending invitation and an accepted collaborator grant, making the tool's scope unambiguous. The title 'Revoke App Share' reinforces the purpose without adding new information.

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 tells when to use the tool: 'Use this when the user wants to withdraw an invitation or remove a collaborator.' This is a direct, actionable condition that leaves no ambiguity about when to invoke it. While it does not name an alternative tool, no sibling provides the same functionality (share_app is the opposite, but the description doesn't need to state that since this is the only revoke 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?

The description richly discloses behavior: synchronous publishing for existing-contract saves, async ESM builds that keep the last active app running, atomic edits with revision gating, and the warning that `url` is machine-only with a write-capable token while `shareUrl` is for users. This goes well beyond the annotations' destructive/openWorld hints and does not contradict them.

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

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

The description is long but front-loaded with the core update purpose and sync/async behavior, and every paragraph adds new guidance (migration, docs reference, sharing semantics). It earns its length for a 10-parameter tool, though it repeats some 'mutually exclusive' information that already lives in the schema.

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

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

For a tool this complex, the description covers input shapes, concurrency controls, polling, contract migration, output fields, and a pointer to full docs, while the output schema covers return values. Nothing an agent needs in order to call it correctly is missing.

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

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

With 100% schema coverage, the schema already documents the parameters, and the description builds on it by explaining when to pass an updated `description`, when `idempotency_key`/`expected_revision` are required, and how `shareUrl` vs `url` relate to the result. It adds cross-cutting semantics without needing to re-document each parameter.

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

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

The description opens with a specific verb+resource ('update an existing Charming app identified by UUID') and immediately lays out the two input shapes, so an agent knows what the tool does. It distinguishes from create_app by emphasizing existing apps, but it never differentiates from the sibling mutate_app, so it is not quite a 5.

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 concrete when-to-use context: existing-contract saves publish synchronously, ESM saves require idempotency_key/expected_revision and should be polled via get_app_build, and full-source vs edits[] are mutually exclusive. It does not explicitly name alternatives or say when not to use this tool versus mutate_app or other siblings.

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

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

Annotations establish that this is a non-read, non-destructive mutation, and the description adds a genuinely useful behavioral detail: re-enabling resets the consecutive-failure counter. This goes beyond the schema and informs the agent of a side effect that affects downstream reasoning.

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, information-dense sentences with no filler. The most important usage instruction is front-loaded, and the inline JSON example communicates the re-enable semantics more efficiently than prose would.

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 small parameter set, 100% schema description coverage, existing output schema, and annotations already indicating a safe mutation, the description covers the essential operational and behavioral context. An agent has everything needed to 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 coverage is 100%, so the baseline is 3. The description adds meaning to the `enabled` parameter by making the exact payload shape explicit (`{enabled: true}`) and by explaining the reset behavior on re-enable, which is not inferable from the schema alone.

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

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

Names a specific action ('change'), a specific resource ('a Routine'), and narrows the scope to exactly two operations: modifying the interval or toggling enabled state. The re-enable example further clarifies exactly what the tool does, leaving no ambiguity about its role relative to create/delete/list 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?

Explicitly states when to use the tool ('Use this to change a Routine's interval, or enable/disable it') and clarifies that re-enabling is done through this same tool ('there is no separate re-enable action'). It doesn't name alternative sibling tools, but the CRUD context makes the selection obvious.

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 adds meaningful behavioral detail: the server fetches sourceUrl and follows redirects, bytes never transit through the tool call, base64 payloads can stall MCP clients around 16 KB, and caps are 10 MiB/asset, 50 assets/app, 100 MiB/app. It does not disclose what happens when uploading with an existing key, though the destructiveHint annotation is present but not elaborated.

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

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

The description is dense and front-loaded with the core purpose, then immediately moves into how to invoke it, then into retrieval and caps. Every sentence earns its place, although it is still a long single paragraph that could be easier to scan as bullets or as separate paragraphs.

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 6-parameter schema, annotations, output schema, and caps, the description covers the contract well: source selection, binary safety, retrieval APIs, and size constraints. The main gap is that it does not explain the overwrite/destructive behavior of reuploading an existing key, and it assumes the reader knows their app ownership requirement is enough.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds selection semantics above the schema: lasering xactly one way, source precedence, and size guidance for source vs base64. Some of this duplicates the parameter-level descriptions in the schema, so not a 5.

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 opening phrase 'UPLOAD A STATIC ASSET TO AN APP' gives a specific verb, resource, and target. It also distinguishes itself from code inlining by mentioning the 256 KiB source cap and static files (images, PDFs, datasets), which an agent can use it aside from sibling 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 explicitly says 'Use this when an app needs a large or static file... would otherwise be inlined into module/ui'. It also tells the agent to provide EXACTLY ONE of sourceUrl/text/dataBase64, and gives clear selection rules ('PREFERRED for any binary', 'LAST RESORT', 'use sourceUrl for anything bigger'). This gives the agent direct guidance on when and how to invoke.

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