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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=true), the description discloses meaningful behavior: it 'creates or reuses a normalized-title match,' preserves placement verbatim, 'optionally resolves Slack,' and returns 'exact Swift plus mandatory edit/build/test actions.' The warning that remote creation alone is not completion adds essential context for agent workflow. No contradiction with annotations.

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

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

The description is a single dense sentence that front-loads the usage condition and packs in the key behavioral notes. Every clause adds value; no redundant wording. It is slightly long but appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (7 parameters, 4 required, output schema present), the description is remarkably complete. It covers the trigger, the creation/reuse behavior, Slack resolution, the exact return value (Swift plus mandatory actions), and the completion criteria. The presence of an output schema reduces the need to explain return structure, and the description compensates with workflow guidance.

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 seven parameters are fully documented. The tool description adds a little context (e.g., 'normalized-title match' hints at title matching logic, 'optionally resolves Slack' aligns with slack_channel) but does not provide significant additional semantic value beyond the schema. 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 a specific verb and resource: 'Creates or reuses a normalized-title match' for a 'named feedback form at a screen, button, lifecycle moment, or in-app action.' It distinguishes from generic form tools by emphasizing the placement-specific, named-form behavior and the reusability, which separates it from simpler create/update 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 explicitly states when to use the tool: 'Use this when the user asks for a named feedback form at a screen, button, lifecycle moment, or in-app action.' It also provides a completion requirement ('Remote form creation alone is not completion') but does not mention alternatives or exclusions, so it misses the 'when-not' aspect for a top score.

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

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

Annotations already 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 discloses key behaviors beyond the annotations: it returns authorization_url, session_id, and finish_arguments immediately, and it never launches a browser, sleeps, or polls. This gives the agent concrete expectations about the tool's execution and side effects, which the annotations alone do not provide.

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

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

The description is three sentences long and front-loads the critical usage context. It avoids redundancy and every sentence contributes meaningful information: when to use, what to pass, and what to expect in return.

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

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

Given the tool's complexity (7 optional parameters, output schema present), the description is complete: it explains the scenario, the required pre-step, the inputs to gather, the immediate return values, and the absence of blocking behavior. The output schema is not included but is available separately, so no essential information is missing.

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

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

The input schema has 100% coverage with descriptions for all parameters, so the baseline is 3. The description adds minimal parameter-specific insight beyond saying to pass 'app identity, use cases, and subscription provider,' which loosely maps to the schema fields but does not provide additional syntax or constraints 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 clearly states the tool's purpose: initiating Paydirt setup for a new user, machine, or iOS app before authentication. It uses a specific verb ('begin setup') and differentiates from siblings by specifying the exact condition (authentication not completed) and the expected outputs.

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 ('when installing Paydirt for a new user, machine, or iOS app and authentication has not been completed') and provides a prerequisite ('Inspect the host first'). It also implicitly distinguishes from later steps by mentioning 'finish_arguments' and stating what it does not do (launches browser, sleeps, polls), helping the agent decide when this is the right action.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds valuable context: authorization creates a new #paydirt-cancellation-feedback channel (numbered when taken) and auto-assigns installed forms when workspace policy allows. This goes beyond the annotations and clarifies the post-authorization side effects. It does not contradict the readOnlyHint because the tool itself only returns the URL; the side effects occur during external authorization.

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 gives the trigger and return value; the second sentence explains the important post-auth behavior. 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?

With an output schema present and high schema coverage, the description covers everything essential: trigger, return value, and downstream side effects. It is complete for the tool's complexity and works well with the sibling 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 input schema has one parameter, app_id, with a description ('The app ID'), so schema coverage is 100%. The tool description does not add any extra parameter-specific 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 states exactly when to use the tool ('when the user asks to connect Slack or setup requires Slack delivery') and what it returns (the Slack OAuth URL). This clearly distinguishes it from siblings like paydirt_slack_status and paydirt_list_slack_channels, which cover status and channel listing rather than the connection flow.

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 names trigger conditions for using this tool. It does not explicitly name when not to use it or alternative tools, but the given context is clear enough for an agent to select it appropriately.

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 adds valuable behavioral context beyond annotations: it returns immediately (no long-polling), does not loop or sleep on pending state, and securely saves credentials when ready. It also states the return includes a 'complete host-app installation, Slack, build, and verification contract,' which is useful even with an output schema. The annotations already indicate non-readOnly and idempotent, so this is complementary, not contradictory.

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 when-to-use condition, and every clause serves a purpose: triggering context, behavior (returns immediately, no loop), and outcome (saves credentials, returns contract). No filler or redundancy.

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

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

For a complex setup tool with 8 parameters and an output schema, the description provides the essential context: the exact trigger (after user opens authorization URL), the single-session check behavior, the no-polling directive, and the final outcome. It does not describe what happens if the session is invalid or expired, but that is likely covered by error responses or output schema. Overall, it's well-rounded and sufficient for an agent to use 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 input schema provides descriptions for all 8 parameters, achieving 100% coverage. The description itself adds no parameter-specific semantics beyond referencing session_id as coming from begin_setup, which is already stated in the schema. Therefore, it meets the baseline for high schema coverage but does not exceed it.

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 function: completing setup after the user has opened the authorization URL. It specifically identifies the action ('checks one setup session'), the resource ('setup session'), and the outcome ('saves credentials and returns the complete contract'), distinguishing it from the sibling paydirt_begin_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 says 'Use this when the user has opened the authorization URL returned by paydirt_begin_setup,' giving a precise trigger condition. It also provides a critical exclusion: 'If pending, do not loop or sleep,' which guides the agent's behavior in a polling context. This is strong usage guidance.

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

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

Annotations already declare 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 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?

The description adds critical behavioral details not present in annotations: it never opens a browser or blocks, returns authorization_url plus finish arguments on first call, and returns pending/expired/complete contract on subsequent calls. No contradiction with existing 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, front-loaded, with no fluff. Every sentence earns its place: when to use, what happens in each mode, and what it does not do.

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

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

Despite having 8 parameters, the description is complete for the tool's purpose: it defines the compatibility scope, alternative tools, dual-mode behavior, and non-blocking guarantee. The presence of an output schema means return values need not be described.

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

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

The schema already covers all 8 parameters with 100% description coverage, so baseline is 3. The description adds meaningful semantic detail for session_id, explaining that its presence changes the call to behave like paydirt_finish_setup. This extra context justifies a 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 this as a compatibility wrapper for older clients, distinct from the newer paydirt_begin_setup and paydirt_finish_setup tools. It specifies the core behavior (start setup or check status) and the title 'Compatibility' reinforces the 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?

It explicitly states when to use the tool ('when an older client expects the single setup tool'), when not to use it ('New agents should prefer paydirt_begin_setup and paydirt_finish_setup'), and how behavior changes based on presence of session_id. This is exemplary guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds what the tool reports (channel and form assignment status) and a conditional behavior (fallback to channel selection), which goes beyond the annotations without contradicting them.

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

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

Two sentences, front-loaded with the primary usage context, and no wasted words. Every sentence contributes purpose, timing, or alternative behavior.

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

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

For a status-checking tool with an output schema, the description fully covers when to use it, what it reports, and what to do in edge cases. Nothing critical is missing.

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

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

The single parameter app_id is fully described in the schema ('The app ID') with 100% coverage. The description does not add parameter-specific details, but the baseline 3 applies because the schema carries the burden.

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

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

Description clearly states the tool's purpose: to report the created Paydirt cancellation feedback channel and whether every installed form is assigned. The verb 'reports' plus the specific resource (Slack status after authorization) distinguishes it from siblings like paydirt_connect_slack or paydirt_list_slack_channels.

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

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

Explicitly states when to use: 'when Slack authorization has finished and before declaring setup complete.' It even gives an alternative action ('List or select channels') for a specific condition (automatic creation blocked or user requested another channel), providing clear when/when-not 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.