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

The description discloses that the tool creates or reuses a normalized-title match and that retries update an existing matching form, which is consistent with the idempotentHint. It also reveals the mandatory edit/build/test actions and non-completion of remote creation, adding useful behavioral context. The destructiveHint is not contradicted, though the description could more explicitly warn about overwriting existing forms.

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 information-dense, with no filler or redundant phrasing. It front-loads the trigger condition and then packs necessary behavior, output, and workflow constraints into a small number of sentences. Every clause adds operational 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 number of parameters and the presence of an output schema, the description covers the main decision points: when to use it, what it returns, required follow-up actions, and Slack deferral. It could be slightly more explicit about failure modes or exact output shape, but the output schema is expected to carry that detail.

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

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

Every parameter is described with concrete semantics beyond its name, such as preserving placement text verbatim, explaining trigger enum values, defaulting initial_question, and instructing to discover app_id via setup/list_apps. The 'retry updates existing form' note for initial_question adds important idempotent behavior. This goes well beyond the schema descriptions alone.

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

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

The description clearly identifies the target action: adding a named feedback form at a specific placement, with create-or-reuse behavior based on normalized titles. It distinguishes this from generic form creation by anchoring it to screens, buttons, lifecycle moments, and in-app actions, and the sibling list reinforces that separate form tools exist.

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 starts with 'Use this when...' and describes the triggering user intent, which is strong usage guidance. It also states that remote form creation alone is not completion and that Slack is deferred until after visual verification, giving practical workflow direction. It does not explicitly name alternative sibling tools, but the trigger conditions are clear enough.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds 'Reads actual responses and returns analysis without taking action,' which reinforces the read-only nature but does not reveal additional behavioral nuances like rate limits, authentication needs, or pagination. With annotation coverage, the bar is lower, so a score of 3 is appropriate.

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

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

The description is two sentences, front-loaded with the key usage trigger, and contains no redundant or irrelevant information. Every word contributes to understanding the tool's purpose and behavior.

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

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

Given that an output schema exists, the description does not need to explain return values. With full parameter documentation, the description sufficiently conveys the tool's purpose and usage context. A minor improvement could be explicit differentiation from paydirt_get_summary or paydirt_get_responses, but the current description is adequate for selection and invocation.

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

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

The input schema has 100% description coverage for all parameters. The description adds no significant new parameter semantics beyond examples like 'pricing themes or feature requests,' which mirrors the schema's example for the 'question' parameter. Since the schema fully documents each parameter, the baseline of 3 is correct.

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 answers natural-language analytical questions about Paydirt feedback, such as pricing themes or feature requests. It distinguishes itself from sibling tools like paydirt_get_responses by emphasizing analysis rather than raw data retrieval, and explicitly notes it takes no action.

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 an explicit trigger condition: 'Use this when the user asks a natural-language analytical question about their Paydirt feedback.' This gives clear guidance on when to use the tool, though it does not explicitly mention alternatives or when-not-to-use scenarios, so it stops short of a 5.

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

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

The description clearly says that without form_plan_confirmed it will not start authorization, and that after confirmation it returns authorization_url and finish_arguments. It does not disclose side effects such as creating or updating apps, whether the operation is idempotent, or what happens if required steps are skipped.

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

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

The description is front-loaded with 'Use this when' and includes only relevant workflow information. However, it is a single dense run-on paragraph with awkward phrasing like 'voice cancellation feedback' and 'concise cancellation/Suggest a Feature confirmation', making it less clear than it should be.

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 multi-step setup flow, the description covers the main state transition (confirmation before authorization, then receiving authorization_url) and mentions app_id reuse. It lacks specifics about how to inspect the host, what the output schema contains, or failure/error conditions, but it does provide enough for basic use.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds flow context for app_id, use_cases, form_plan_confirmed, and feature_placement, but most parameter meaning already lives in the schema and several parameters like app_name, subscription_product_ids, and uses_revenuecat are not enriched.

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

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

The description names the specific action—beginning setup for feedback forms and Slack connection—and gives enough detail to distinguish it from siblings like paydirt_setup and paydirt_finish_setup. However, the phrase 'voice cancellation feedback' is confusing and likely a typo, which prevents a perfect score.

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 states when to use the tool (installing feedback forms, connecting Slack, browser authorization), how to handle website-started setups via app_id, and the confirmation gate before authorization. The instruction 'Inspect the host first' is vague and no explicit alternatives are mentioned, so it falls short of 5.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, which cover the safety profile. The description adds that the tool returns an OAuth URL and mentions the browser flow, giving extra behavioral context. It does not contradict the annotations and adds a small but useful detail about preserving channel choices and only sending completed Q&A.

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 about three sentences and remains focused. It starts with the core purpose, then explains the return value, and finally adds operational caveats. No unnecessary filler, though the last sentence about preserving choices and verifying assignments feels slightly tangential but still relevant to usage.

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

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

The description covers purpose, when to use, and a general return type (OAuth URL). However, it lacks details about the output structure (e.g., the exact URL format or how the agent should handle it) and does not fully clarify what 'repair Slack delivery' entails. It also doesn't explain the app_id parameter's origin or significance, leaving some gaps for an agent encountering this tool for the first time.

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 described in the schema as 'The app ID', which is adequate. The description does not add extra semantic information about app_id beyond the schema, so it stays at the baseline. Since schema coverage is 100% (one parameter fully described), the description need not elaborate further, but it also doesn't offer any additional insight.

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 main purpose: to connect Slack or repair Slack delivery after onboarding. The verb 'connect' is specific, and the resource (Slack) is unambiguous. It distinguishes from sibling tools like paydirt_slack_status (status) and paydirt_list_slack_channels (channel listing) by focusing on the OAuth connection action.

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 ('when the user asks to connect Slack or repair Slack delivery after onboarding'). It also provides some operational guidance (preserve channel selections, verify form assignments, only send completed Q&A). However, it does not explicitly mention alternatives like paydirt_slack_status for checking existing connections or paydirt_list_slack_channels for listing channels, leaving some room for ambiguity in tool selection.

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=false and destructiveHint=false, so the description's 'Creates a new app' adds little beyond that. It introduces a useful caution about duplication but does not disclose other behavioral aspects like duplicate handling, side effects, or failure modes. With annotations covering the safety profile, this is acceptable but not rich.

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

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

The description is two sentences, each earning its place: the first gives the usage condition, the second states the action and the important duplication warning. No redundant wording.

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 full parameter descriptions and an output schema, the description covers the primary use case and includes the key pre-check for duplication. However, it omits details about failure behavior or what happens if a duplicate name is provided, but the guidance to list existing apps mitigates this gap.

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

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

The input schema has 100% coverage with descriptive entries for name, bundle_id, and app_description. The tool description does not add any additional parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states 'Creates a new app' with a specific verb and resource, and clarifies the exact scenario for use ('when the user explicitly needs a separate Paydirt app and setup cannot reuse or create it'). It distinguishes this tool from siblings like paydirt_setup and paydirt_list_apps by mentioning duplication checks.

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 and when not to, advising to 'list existing apps first when duplication is possible.' It also references the alternative that setup may reuse or create the app, giving clear selection criteria among the 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 indicate readOnlyHint=false and destructiveHint=false, but the description adds meaningful behavioral context beyond that: it clarifies that this creates a low-level form, maps feedback types, returns an ID, and expects Slack assignment. It also implies a safety step (checking for existing forms), which is useful. No contradiction with annotations; slight deduction because it doesn't explicitly mention the output schema despite 'returned ID' implying a response.

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

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

Three sentences, each with a clear role: usage trigger, prerequisite/mapping, and preference for an alternative. The description is front-loaded with the primary use case and contains no filler or redundant restatement of the schema. It crams a lot of useful guidance into a compact form without feeling overloaded.

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 moderate complexity (5 params, one enum) and rich supporting context (output schema, annotations, sibling tool list), the description covers all necessary angles: when to use, what to check first, how to map enum values, what to do with the result, and which alternative to prefer. The required parameters are all implicitly addressed, and the description is complete enough for an agent to invoke the tool correctly without further clarification.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds domain-specific meaning by explaining how to map real-world concepts to the 'type' enum: 'Map subscription cancellation to cancellation, trial cancellation to trial_expiration, and regular feedback to custom.' This goes beyond the raw enum labels and helps the agent select the correct type value. It also ties 'wire the returned ID into iOS and assign Slack' to the expected output, adding context for parameters like app_id and name.

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

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

The description begins with a specific verb and resource: 'creating a low-level remote form without a host-app placement request.' It clearly distinguishes this tool from paydirt_add_feedback_form by stating that the latter is preferred for named screen or action placement. This makes the purpose immediately clear and differentiated from siblings.

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

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

The description gives explicit when-to-use guidance ('Use this when creating a low-level remote form without a host-app placement request') and explicitly names the alternative tool to prefer for different scenarios. It also provides actionable pre-flight steps ('First confirm a matching form does not exist') and post-creation steps (wire the returned ID into iOS and assign Slack), fully covering usage context.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description does not need to re-state destructiveness. It adds value by emphasizing 'permanently' and the need for inspection before deletion when identity is uncertain. This goes beyond the annotations by providing a safeguard behavior.

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

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

The description is only two sentences, with no filler. It front-loads the primary directive and then provides a necessary caveat. 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 destructive delete operation with one parameter and an output schema, the description covers the key aspects: when to use, the destructive nature, and a caution about identity. It could mention the irreversible effects on associated data, but the annotations and output schema likely cover return details. Overall, it is sufficiently complete for an agent to act 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%, with form_id described as 'The form ID to delete.' The description adds no additional parameter specifics, but with full schema coverage, the baseline is 3. The description's mention of 'specific form' aligns with form_id but does not enrich meaning beyond the schema.

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

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

The description clearly states the tool's action: 'permanently delete a specific Paydirt form.' The verb 'delete' plus resource 'form' distinguishes it from sibling tools like update or toggle. The title 'Delete Feedback Form' in annotations reinforces this purpose.

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

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

Provides explicit instruction on when to use: 'when the user explicitly asks to permanently delete.' It adds caution about inspecting the form when identity is uncertain, which gives practical context. Does not explicitly name alternative tools, but the condition is clear enough for an agent to differentiate from read or update operations.

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

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

The description discloses key side effects and behavior: it checks one session, returns immediately, does not block, and securely saves credentials when ready. It does not contradict the annotations, and it adds useful non-obvious context about not polling or sleeping.

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 well structured: the trigger condition comes first, followed by the immediate return behavior, the anti-loop instruction, and the eventual outcome. Every sentence contributes essential usage context without redundancy.

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

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

The description gives enough workflow context to call the tool correctly: it references the prior begin_setup step, explains the pending state behavior, and states what will be returned once setup is ready. It does not explain every failure mode, but the output schema and annotations cover the remaining contract sufficiently.

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 every parameter already has a meaningful description, including enum guidance and deprecation notes. The tool description itself does not add much parameter-level meaning beyond what the schema provides, so the baseline score applies.

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

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

The description clearly states a specific action: finish the setup flow initiated by paydirt_begin_setup. It names the exact trigger condition, the single-session check behavior, and the eventual credential-save and return contract, making it easy to distinguish from sibling setup and management 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 when to use the tool: after the user has opened the authorization URL from paydirt_begin_setup. It also gives direct operational guidance: check once, return immediately, and do not loop or sleep if pending, which prevents common misuse.

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

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

Annotations already declare readOnly, idempotent, openWorld, and destructive=false. The description adds the specific data returned (identity, bundle ID, SDK key, configuration) and reinforces non-modification, providing useful context beyond the 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?

The description is two concise sentences, front-loaded with the use case ('Use this when...'), and contains no filler or redundant content beyond reinforcing the read-only nature.

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 (one parameter, no nested objects, output schema present), the description adequately covers the return contents and non-modifying behavior. It is complete for a single-app getter with strong annotations.

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

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

Schema coverage is 100% for the single app_id parameter, which is already described in the schema. The description adds minimal semantic value by implying the app_id identifies the known app, but this is already clear from the schema and the phrase 'one known Paydirt app.'

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

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

The description clearly states the tool retrieves current identity, bundle ID, SDK key, or configuration for one known Paydirt app, using a specific verb (get) and resource (app). It distinguishes itself from sibling tools like list_apps (which lists all apps) and create/update 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 directs use when needing details for one known app, implying the need for a specific app_id and contrasting with listing all apps. It also notes 'Does not modify the app,' which steers away from mutating tools, though it does not explicitly name alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the bar is lower. The description adds a useful downstream directive ('Never turn feedback into code changes or tasks automatically') and reinforces the read-only nature, but contributes little about tool-side behavior such as error cases, rate limits, or empty-result handling. The extra context is helpful but minimal.

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: it opens with the usage trigger, then summarizes the output, then adds a short closing constraint. There is no filler or redundancy. The final sentence is policy-oriented rather than descriptive, but it is brief and relevant, so the overall structure is solid.

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 only two parameters (both well-described in the schema) and an output schema present, the description adequately summarizes the key deliverables (totals by type, period comparison, highlights). It does not cover error behavior or empty-result scenarios, but given the low complexity and schema support, nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100% — both app_id and hours have meaningful descriptions, including the period-comparison semantics and min/max bounds. The description reinforces the 'comparison with the previous equal period' concept but adds no new parameter meaning beyond what the schema already conveys, so the baseline score 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 states a specific resource ('read-only daily or periodic Paydirt brief'), specifies what it returns (completed-response totals by feedback type, comparison with the previous equal period, concise highlights), and distinguishes it from siblings like paydirt_get_responses and paydirt_get_summary. It would earn a 5 if it explicitly named the sibling alternatives; it stops just short of that.

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

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

Provides a clear when-to-use trigger ('when the user or a scheduled task needs a read-only daily or periodic brief') and an explicit non-action ('Never turn feedback into code changes or tasks automatically'). However, it does not explicitly contrast with sibling tools (e.g., when to prefer get_responses vs get_summary vs this digest), so the guidance is present but implicit about alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying exactly what fields are retrieved (prompt, type, enabled state, Slack assignment) and confirming non-modification. It aligns with annotations and provides context beyond them, though it does not address error cases like invalid form_id.

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

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

Two sentences, front-loaded with the usage trigger, and zero wasted words. Every phrase earns its place: what to retrieve, scope, and non-modification. Excellent conciseness for a simple read tool.

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

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

Given the low complexity (one parameter, output schema present, annotations covering safety), the description is fully sufficient. It covers when to use, what is retrieved, and the non-modifying behavior. No critical gaps remain for an agent to invoke it correctly.

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

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

Schema description coverage is 100% with form_id documented as 'The form ID.' The description adds the context that it is for 'one known form,' which implies the ID must reference an existing form. This is marginal added value beyond the schema, earning the baseline 3 for high coverage.

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

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

The description clearly states the tool retrieves the current prompt, type, enabled state, or Slack assignment for one known form. It uses the specific verb 'get' with a resource ('form') and scope ('one known form'), distinguishing it from siblings like paydirt_list_forms (which lists all) and paydirt_update_form (which modifies).

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 the agent needs...' providing a clear when-to-use condition. It also includes a when-not clause with 'Does not modify the form,' implying it is not for modifications. However, it does not explicitly name an alternative tool (e.g., paydirt_update_form), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by disclosing the default status filter (completed), the recommended incremental read pattern using 'since' and 'updated_at', and a safety warning against automatic actions. No contradictions.

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

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

Two sentences, front-loaded with the purpose, and every phrase adds meaning. No redundant or filler information; concise yet informative.

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

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

For a read-only list tool with no output schema, the description covers what data is returned (raw conversations, Q/A turns, etc.), the default status filter, and a key usage pattern. It is sufficient for the moderate complexity, though it could mention pagination or return format more explicitly.

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 covers 100% of parameters with descriptions, so baseline is 3. The description adds extra semantic value beyond the schema by explaining how to use 'since' with 'updated_at' for incremental reads, which is not in the schema. This elevates the score to 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 clearly identifies the tool as retrieving raw feedback conversations, exact Q/A turns, input type, subscription metadata, and a read-only inbox cursor. The verb 'get' and resource 'responses' are specific, and the detail about raw vs. summary data distinguishes it from siblings like paydirt_get_summary.

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 ('when the user or coding agent needs raw feedback conversations...') and provides operational guidance (incremental reads with since, never take action automatically). It does not name specific alternatives or state when not to use it, 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?

Annotations already declare readOnly/idempotent/non-destructive, so bar is lower. The description adds that the summary is supplementary and not the source of truth, which is important context about reliability. This goes beyond structured hints.

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

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

Two concise sentences. Front-loaded with usage trigger, immediately answers when to use. No wasted words.

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

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

For a simple read-only summary tool with all parameters schema-described and an output schema present, the description sufficiently covers purpose, usage, and trust caveat. Nothing material 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 covers 100% of parameters with descriptions. The tool's description adds no parameter-specific meaning; it doesn't mention days, form_id, or app_id. Baseline 3 is appropriate.

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

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

The description clearly states the tool produces an aggregate AI summary of recent Paydirt responses, using a specific verb+resource. However, it does not explicitly name sibling alternatives like paydirt_get_responses, relying on the word 'summary' to differentiate.

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

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

Provides explicit trigger condition ('when the user asks for an aggregate AI summary') and clarifies that raw Q&A are the source of truth, implying to use raw response tools for detailed data. It doesn't name the alternative tool, so not a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context beyond annotations by specifying it is a connectivity check that validates stored authentication, which gives useful behavioral context without contradicting any annotations.

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

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

The description is two sentences, front-loaded with the usage context, and contains no redundant information. Every word earns its place, making it concise and well-structured.

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

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

Given the tool's simplicity (no parameters, output schema exists), the description is complete: it explains the purpose, usage context, and the read-only nature. No additional behavioral details are needed to select or invoke it correctly.

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

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

The tool has zero parameters, so the schema provides no parameter semantics. Per the baseline for 0 params, a score of 4 is appropriate. The description does not need to explain parameters, but it does implicitly clarify that no input is required.

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

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

The description uses a specific verb and resource: diagnosing Paydirt API reachability and authentication validity. It clearly distinguishes this tool from sibling CRUD operations (e.g., paydirt_list_apps, paydirt_create_form) since none other performs a health check.

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

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

The description explicitly states when to use: 'Use this when diagnosing whether the Paydirt API is reachable and stored authentication is valid.' No alternative tool is needed because no sibling serves this purpose; the guidance is direct and unambiguous.

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

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

Annotations already define readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context by specifying 'authenticated Paydirt account' and reinforces 'without changing them', which aligns with the annotations. It does not introduce contradictions. Slight extra context beyond annotations justifies a 4.

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

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

The description is only two sentences, front-loaded with the usage context in the first sentence, and straightforward action in the second. Every word earns its place, no redundancy or fluff.

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

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

For a zero-parameter list tool with no output schema, the description provides sufficient context: it names the action (list all apps), scoping (authenticated account), and non-mutating behavior. It also explains a practical use case (resolving app ID after setup). This fully covers the tool's simple purpose.

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

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

There are zero parameters, and schema coverage is 100%. Per the rubric, the baseline is 4. The description does not need to elaborate on parameters, but it does implicitly mention resolving app IDs, which hints at the output relevance.

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

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

The description clearly states the tool 'Lists all apps for the authenticated Paydirt account', using the specific verb 'Lists' and resource 'all apps'. It distinguishes from siblings like paydirt_get_app (single app) and paydirt_create_app by focusing on the listing action and the 'without changing them' safety note.

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

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

The description explicitly says when to use it: 'when the user asks which Paydirt apps exist or when an agent must resolve an app ID after setup'. It does not explicitly mention alternatives or when not to use, but the context is clear. A score of 5 would require explicit when-not/alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the read-only nature is well covered. The description adds the 'resolve or deduplicate' use case and reiterates non-modification, but does not disclose return format, pagination, or open-world behavior beyond what annotations imply. 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 a single, front-loaded sentence that immediately states the trigger condition, tool purpose, and a key constraint. Every phrase earns its place with no waste.

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

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

For a simple one-parameter list tool with strong read-only annotations and no output schema, the description adequately conveys when to use it and that it is non-mutating. It doesn't detail the return shape, but 'which forms exist' implies a list result, which is sufficient given the tool's simplicity.

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

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

The single parameter app_id is fully described in the schema as 'The app ID' (100% coverage). The description does not add additional parameter detail, so the baseline score of 3 is appropriate because the schema already carries the meaning.

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

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

The description clearly states the tool lists forms ('which forms exist') for a Paydirt app, using a specific verb and resource. It also distinguishes from siblings like get_form (single form) and create_form/update_form/delete_form by noting it does not modify forms.

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

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

The description explicitly says when to use the tool: when the user asks which forms exist or when the agent needs to resolve/deduplicate forms. It lacks an explicit 'when not to use' or named alternatives, but the context is clear and the negative statement 'Does not modify forms' helps guide selection.

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. The description adds domain-specific non-mutation context ('without changing assignments') and an environmental prerequisite ('when Slack is connected'), which go beyond the annotations to clarify behavior.

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

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

Two sentences, front-loaded with usage, no redundant phrasing. Every word adds value, making it highly efficient for an agent to parse.

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

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

The description covers the purpose and usage trigger, annotations cover the safety profile, and the output schema exists for return values. Nothing essential is missing for this simple, read-only list tool.

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

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

Schema coverage is 100% with app_id having its own description ('The app ID'). The tool description does not add further parameter details, but the baseline of 3 applies since the schema handles parameter semantics.

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

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

The description explicitly states the tool's function: 'Lists available channels' with a specific use case ('resolve a requested channel name to its channel ID'). This clearly distinguishes it from sibling tools like paydirt_list_forms or paydirt_slack_status.

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

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

The description opens with a clear trigger condition: 'Use this when Slack is connected and the agent must resolve a requested channel name to its channel ID.' It does not explicitly mention alternatives, but the usage context is unmistakable and sufficient for a list-only tool.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds value by specifying that the tool replaces the current channel assignment (the destructive effect) and should be verified afterward, giving context for the destructive nature. No contradiction with annotations.

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

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

Two short sentences, front-loaded with the triggering condition, followed by the effect and a caution to verify. Every sentence earns its place; no wasted words.

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

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

For a simple 3-parameter tool with full schema coverage, annotations covering safety traits, and an output schema present, the description fully captures the purpose, effect, and post-step. It is complete for its complexity and provides the necessary context for correct invocation.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds minimal extra meaning beyond the schema—it mentions the context of Slack channel delivery but doesn't elaborate on parameter syntax or relationships. Baseline 3 applies since 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 clearly states the tool's specific action: assigning a form's delivery to a specific Slack channel ID, and explicitly notes it replaces the current assignment. This distinguishes it from siblings like update_form (general updates) and toggle_form (enable/disable).

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

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

The description provides a clear 'when to use' condition ('when a form must deliver completed conversations to a specific Slack channel ID') and advises verification afterward. It doesn't mention alternatives or exclusions, but the condition is specific enough to guide correct selection.

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

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

Discloses that it never opens a browser or blocks, and explains what happens with and without session_id. It does not explicitly state that setup may create or reconfigure an app, but the annotations and description make the mutating nature reasonably clear.

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 bit long but each sentence serves a purpose: compatibility guidance, behavior distinction, non-blocking assurance, and sibling preference. The parameter descriptions add necessary nuance without being redundant.

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 explains the tool's role, its two modes, return behavior, and relationship to sibling tools. It gives enough context for an agent to decide when and how to call it, including the handoff scenario.

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?

Every parameter is documented with meaningful context, including the app_id handoff reuse, use_cases recommendation, subscription_provider preference over deprecated input, and the nuanced form_plan_confirmed behavior. This goes well beyond the schema alone.

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

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

Clearly identifies itself as a compatibility endpoint for older clients and states it either starts or finishes setup depending on session_id. It also distinguishes itself from paydirt_begin_setup and paydirt_finish_setup.

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 when to use the tool ('older client expects the single setup tool') and directs new agents to prefer begin_setup/finish_setup. The session_id-dependent behavior is also clearly explained.

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 the tool is read-only, idempotent, and non-destructive. The description adds clarity that it reports status without side effects, so the behavior is well understood.

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 information-dense, leading with the main use case and then explaining the output. Slight redundancy with 'completed authorization' could be trimmed, but overall it is well structured.

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

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

The description states what is reported (feedback channel and assignment status) and when to use it, which is sufficient for this simple read-only status tool. It does not over-promise or omit critical context.

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

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

The single parameter app_id has a minimal schema description, but the tool description clarifies it is tied to the developer's app. Since schema coverage is 100% and the parameter is simple, the description provides enough context.

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

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

The description clearly states the tool reports the Paydirt feedback channel and whether every installed form is assigned, and distinguishes it from agent-only delivery. This makes the purpose specific 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 says to use this tool when the developer selected Slack or combined delivery and completed authorization, and explicitly says not to call it for agent-only delivery. This gives clear when-to-use and when-not-to-use guidance.

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

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

Goes beyond annotations by explaining that disabled forms are not shown by the SDK and that toggling is reversible. This complements the idempotentHint and destructiveHint annotations, adding valuable behavioral context.

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

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

Two concise sentences with the usage condition front-loaded. Every word earns its place; no fluff or redundancy.

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

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

For a simple toggle tool with full schema coverage, annotations, and an output schema, the description is complete. It explains the core behavior and reversibility, 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?

The input schema already covers both parameters (form_id, enabled) with clear descriptions, so the description adds no additional parameter meaning. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly states the tool's action: 'enable or disable an existing form remotely.' This is specific (toggle) and identifies the resource (form), distinguishing it from sibling tools like create/update/delete forms.

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

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

Provides an explicit 'use this when' condition, linking directly to user intent. It doesn't name alternatives or exclusions, but the context is clear enough for appropriate selection.

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 the important behavioral detail that 'Only supplied fields are updated', which is a partial-update semantics not captured by annotations. Combined with annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true), the agent knows this is a mutating operation, and the description clarifies that unspecified fields are left untouched.

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, zero waste. The first sentence leads with the usage trigger, and the second clarifies the partial-update behavior. 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?

Given the tool has an output schema, 100% parameter coverage, and annotations for destructive/idempotent behavior, the description is sufficient. It clearly states the action, scope, and partial-update semantics, making it complete enough for an agent to select and invoke 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 the schema already explains each parameter clearly. The description groups fields (identity, bundle ID, description, AI context) but does not add meaning beyond what the schema provides, so a 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 specifically states 'change an existing Paydirt app’s identity, bundle ID, description, or AI context', using a clear verb and resource. It clearly differentiates from sibling tools like create_app or get_app by focusing on updates to an existing 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 opens with 'Use this when the user asks to change...', providing an explicit when-to-use condition. It does not explicitly mention when not to use it or name alternative tools, but the context is clear and distinct from creation or deletion.

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

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

Annotations already declare destructiveHint and idempotentHint. The description adds key context that only supplied fields are updated, which is beyond the annotations and prevents incorrect full-replacement assumptions. No contradiction with annotations.

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

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

Two sentences with no filler. The first sentence provides the primary use case immediately, and the second sentence clarifies partial update behavior. 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 simple update tool with a clear output schema, the description covers purpose, trigger, and partial update semantics. It could explicitly mention error behavior for missing form_id, but that is implied by 'existing form' and not essential for tool selection.

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 well-documented. The description adds semantic value by mapping fields to user-facing concepts ('initial question', 'AI follow-up guidance') and explicitly stating that only supplied fields are updated, clarifying the optional and partial nature of the update.

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 updates an existing form's name, initial question, or AI follow-up guidance, using a specific verb and resource. It distinguishes itself from siblings like paydirt_create_form and paydirt_update_app by targeting existing forms and specific fields.

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 asks to change an existing form...') and clarifies partial update behavior. It does not explicitly name alternatives or exclusions, but the scoping is strong enough for an agent to select it correctly.

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