SoapBox Faith

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

Beyond the annotations (readOnlyHint=true, openWorldHint=true), the description discloses the response format (grounded answer with public-domain KJV citations) and the tool's scope as a study aid, not a substitute for pastoral or professional care. This adds meaningful behavioral context not present in annotations.

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

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

The description is concise and well-structured: it front-loads the action and result, then adds critical limitations and usage guidance. Every sentence serves a purpose with 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 tool with one parameter, no output schema, and relevant annotations, the description comprehensively covers what the tool does, what it returns, its limitations, and when to use it. It is complete enough for an agent to select and invoke the tool correctly without external documentation.

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

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

The input schema already fully describes the single parameter 'question' (a natural-language Bible/faith study question) with examples and length constraints, achieving 100% coverage. The description does not add additional parameter-level detail, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific action (ask ORA a Bible or faith question) and the resource (SoapBox's Scripture study aid), with a distinct outcome (returns grounded answer citing KJV passages plus citations). It also explicitly differentiates from the sibling tool get_verse, making its purpose unmistakable.

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

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

The description provides explicit when-to-use guidance for explanatory/study questions and names the alternative (get_verse) for simple verse lookups. It also clarifies limitations, directing users to trusted professionals for personal crises, which prevents 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 readOnlyHint=true and destructiveHint=false. The description adds valuable context: 'No key required' (auth needs), 'currently consented sermons; reading-plan and devotional bundles coming' (scope/currency), and the exact return fields (id, title, church, price). This enriches beyond the annotations without contradiction.

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

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

Three concise sentences: what it does, what it returns, and a purchase pointer. Every sentence adds value, and the structure is front-loaded with the tool's purpose. No fluff or redundant detail beyond the schema.

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

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

For a simple list/browse tool, the description is complete: it states the products available, return fields, an optional filter, and the follow-up purchase action. With no output schema, the return fields are explicitly listed. OpenWorldHint is covered by annotations, and the 'No key required' note resolves auth concerns.

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

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

The schema covers 100% of parameters with descriptions and examples. The description merely mentions 'Optional church_id and text filter', adding no new meaning beyond what the schema already provides. Given the high schema coverage, the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Browse') with a clear resource ('purchasable faith-content products on SoapBox') and explicitly distinguishes from the purchase step ('Then buy with purchase_sermon'). It also clarifies current scope, making it distinct from sibling tools like search_sermons.

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

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

The description implies a workflow: use browse_catalog to discover products, then purchase with purchase_sermon. It notes the current content scope ('currently consented sermons'), hinting at when this tool is appropriate. However, it does not explicitly state when not to use it or mention alternatives like search_sermons.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds important behavioral context beyond this: it requires a specific consent_token and only returns status for the user's own prayers, disclosing scope and authentication constraints.

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 tool's purpose and then adds necessary conditions. Every word earns its place; there is no redundant or tangential content.

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 status-check tool with only two parameters and no output schema, the description sufficiently conveys what it does (count + answered flag), when it applies (previously submitted), and its access requirements. It is complete for the tool's complexity.

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

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

The input schema already provides 100% coverage with detailed descriptions for both prayer_id and consent_token, including the token scope and ownership restriction. The description merely paraphrases these requirements, adding no new parameter-level 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 clearly states the tool checks 'how many people are praying' and 'whether it's been marked answered' for a previously submitted prayer request. This specific verb+resource combination distinguishes it from sibling tools like submit_prayer_request, which creates requests.

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

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

The description provides clear context for when to use this tool: for a prayer request 'previously submitted,' and it emphasizes the requirement for the same user's consent_token, restricting use to their own prayers. However, it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already declare read-only and non-destructive. The description adds context about the public directory scope, absence of personal contact info, and the specific return fields including distance and SoapBox status, going beyond the annotations.

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

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

The description is two sentences, front-loaded with the main action, and every phrase adds value. 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 no output schema, the description enumerates the return fields and the data scope, which is essential. It does not cover edge cases or error behavior but is sufficient for a straightforward lookup tool 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% with descriptions for all five parameters including types, ranges, and defaults. The description only mentions 'optional radius, denomination filter', which duplicates the schema, adding no new 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 uses a specific verb 'Find' with a clear resource 'churches near a location' and details what is returned. It distinguishes itself from sibling tools like browse_catalog by focusing on church location search.

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

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

The description implies usage when needing nearby churches but does not explicitly state when not to use it or mention alternatives. The note about public data is a constraint, not a comparative guideline.

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 valuable context about what the balance represents (marketplace credits in cents), the inclusion of tier and rate limit in the response, and the location of top-up functionality, going beyond the annotation safety profile.

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, front-loaded sentences. The first sentence states the core purpose and return content; the second adds relevant operational context about top-ups. No unnecessary words.

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

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

No output schema exists, so the description responsibly describes what the caller receives (credit balance in cents, tier, daily rate limit). It also covers the related top-up action, making the tool's role within the system clear. Fully adequate for a parameterless read-only tool.

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

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

The tool has zero parameters, so there is no need for parameter explanation. Baseline for 0 params is 4, and the description appropriately focuses on return values rather than parameters.

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 states the verb 'Check' and the resource 'marketplace credits' with specifics: amount in cents, tier, and daily rate limit. Distinguishes from siblings by focusing on balance for buying sermon access.

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

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

Explicitly states that top-ups are done via the topup API action or portal, clearly implying this tool is only for checking balance and not for topping up. This provides a clear alternative and when-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?

Beyond the readOnly/destructive annotations, the description discloses that it requires explicit user consent, operates under a 'context:read' scope bound to the agent, returns only the declared profile, and never exposes private prayers or journal. It also specifies that an invalid/expired/wrong-scope token yields an authorization error.

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: the first states the action and purpose, the second states the prerequisite, and the third clarifies the returned data and exclusions. Every sentence carries necessary information with no filler.

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

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

For a single-parameter read-only tool with no output schema, the description covers the return contents, boundary (never private prayers/journal), consent requirement, and error condition. This fully equips an agent to invoke the tool 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 already provides a detailed description of consent_token, including its scope, binding, and error behavior, so the description adds little beyond repetition. The description reinforces the token's purpose ('Requires the user's consent_token') but does not introduce new parameter semantics 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 opens with 'Read a user's portable faith context,' a specific verb+resource statement, and enumerates the profile fields (denomination, language, journey, interests). It also states its purpose ('to personalize your responses'), clearly distinguishing it from sibling tools that deal with prayers, sermons, or payments.

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

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

The description provides explicit guidance: 'Use it to tailor tone, tradition, and language,' which indicates the suitable context. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to decide when to invoke it.

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

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

Annotations declare readOnlyHint and destructiveHint, so safety is covered. The description adds that no key is required, that it defaults to today, and that daily readings are excluded due to licensing. This provides useful context beyond annotations.

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

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

Three short sentences with essential information front-loaded. No redundancy, every clause adds value.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers return values, default behavior, exclusions, and authentication. It is fully sufficient given the low complexity.

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

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

Schema covers the single 'date' parameter with format, pattern, examples, and description. The tool description repeats the default-to-today behavior but adds no new meaning beyond the schema. With 100% schema coverage, baseline 3 applies.

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

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

Description explicitly states the verb 'Get' and the specific resource: Western liturgical season, color, RCL year, and major feast for a date. It clearly differentiates from siblings like get_sermon or get_verse by focusing on liturgical calendar data.

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

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

States 'Useful for date-aware, season-appropriate faith content' which gives context. Excludes daily readings with the note about licensing, implicitly steering users elsewhere for readings. However, it doesn't name specific alternative tools, 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, but the description adds significant behavioral context beyond that: the parishioner opt-in requirement, not-found response, and transcript withholding for unpaid sermons with price return. These are critical behavioral traits that annotations cannot convey. No contradiction exists between description and annotations.

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

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

The description is three sentences, front-loaded with the main action and purpose. Each sentence carries essential information: primary function, availability constraints, and pricing behavior. No filler or redundancy. It is concise yet complete, achieving high information density.

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

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

For a two-parameter fetch tool with no output schema, the description covers all critical context: identifying the sermon, opt-in limitations, paid vs. free access, and the recommended purchase flow. It explains return variations (not-found, withheld transcript with price) without needing to enumerate metadata fields. Given the tool's simplicity and the supporting annotations, this description is fully adequate.

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 meaningful context for sermon_id by stating it's 'typically a sermon_id returned by search_sermons', which connects the tool to its sibling workflow. It also clarifies the include_transcript behavior by explaining when the transcript is returned (free or purchased) versus withheld. This goes slightly beyond the schema descriptions.

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

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

The description clearly states a specific verb ('Fetch') and resource ('metadata and optionally the transcript for ONE sermon by its id'). It explicitly distinguishes from siblings like search_sermons (which lists/search) and purchase_sermon (which buys). The scope ('ONE sermon') and the reference to 'sermon_id returned by search_sermons' anchor its unique role.

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

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

The description provides explicit usage context: use after search_sermons to get details for a specific sermon. It also gives an alternative/next step: 'call purchase_sermon first' for paid sermons. It explains when results are not available (opt-out pastors) and distinguishes free vs paid behavior, giving 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the context that the verse is from the public-domain KJV translation, which clarifies the source. However, it does not describe error behavior or the exact return format beyond the implication that the verse text is returned.

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

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

The description is a single sentence that conveys the tool's purpose without redundancy. Every word contributes to understanding the action and scope, making it highly concise.

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

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

Given the simple read-only nature confirmed by annotations and the complete parameter schema, the description adequately covers the core use case. It specifies the translation and addressing scheme, though it doesn't detail return format or error handling. For a tool of this simplicity, this is sufficient.

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

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

The input schema fully describes all three required parameters with descriptions and examples, achieving 100% coverage. The description merely repeats the parameter names ('book, chapter, and verse') without adding additional semantics, so baseline 3 is appropriate.

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

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

The description uses a specific verb 'look up' and clearly identifies the resource as a public-domain KJV Bible verse addressed by book, chapter, and verse. This distinguishes it from siblings like verify_scripture or lookup_strongs, which have different purposes.

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

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

The description implies use when a specific verse is needed but provides no explicit guidance on when to choose this tool over siblings like verify_scripture or get_lectionary. There are no exclusion criteria or alternative tools mentioned.

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

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

The description goes beyond the annotations by disclosing the consent token scope requirement, the passthrough nature with no fee, the cap enforcement, and the need for an idempotency key. These are critical behaviors not specified in the annotations, adding significant transparency.

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

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

The description is a single, dense paragraph with no fluff. It leads with the primary action, then prerequisites, constraints, and idempotency guidance. Every sentence earns its place 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 covers prerequisites, rejection conditions, and idempotency behavior, but since there is no output schema, it fails to mention what a successful response contains (e.g., a confirmation ID). This is a notable gap for a mutation tool where the agent needs to confirm success.

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

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

The schema provides 100% coverage with detailed descriptions for every parameter, including consent_token, amount_cents, and idempotency_key. The tool description adds little beyond restating that amounts are in cents and idempotency key usage, which are already in 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 clearly states the tool's purpose: "Make a one-time donation to a church ON BEHALF OF A USER", which is a specific verb and resource. It also distinguishes this from sibling payment tools by emphasizing the user's pre-authorized caps and consent token.

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

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

The description provides clear prerequisites and constraints: it requires a user's consent_token with 'giving:write' scope and a saved card, and it rejects amounts over caps. It does not explicitly name alternative tools like pay_with_x402, but the context makes it clear this is the right tool for church donations under user authorization.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by explicitly stating the content of the lexicon entry (lemma, transliteration, gloss, definition), giving the agent insight into the return data. This exceeds what annotations alone 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 a single sentence that is front-loaded with the action and resource, and it efficiently lists the key output fields without unnecessary detail. Every word serves a purpose.

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

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

The tool is a simple single-parameter lookup. The description covers the input (Strong's number), the lexicons (Greek/Hebrew), and the expected output (lemma, transliteration, gloss, definition). Given the annotations and schema, the description is fully adequate for an agent to select and invoke the tool correctly.

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

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

The input schema fully describes the strongs_number parameter with pattern and examples, achieving 100% schema description coverage. The description adds no parameter information, but the schema carries the semantic weight, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Look up a Strong's Greek/Hebrew lexicon entry' with the specific data fields (lemma, transliteration, gloss, definition). This specific verb+resource combination distinctly identifies its purpose and differentiates it from sibling tools like get_verse or search_sermons.

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

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

The description implies usage by defining what the tool returns, but it does not explicitly state when to use it versus alternatives. It lacks guidance on when to prefer this tool over others, though the unique purpose makes the context fairly clear.

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

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

Beyond annotations (non-read-only, idempotent, open-world), the description reveals critical behaviors: the two-step flow, the need to first receive HTTP-402 requirements, the on-chain verification, revenue split (church keeps 70%), idempotency per tx hash, and gasless EIP-3009 option. This adds substantial context beyond annotations with no contradiction.

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

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

The description is well-structured with numbered steps, front-loaded purpose, and every sentence carries essential information—payment mechanics, verification, revenue share, idempotency, and gasless alternative. No unnecessary 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?

Given the tool's complexity (two-step payment, reversible? no output schema), the description is exceptionally complete: covers the exact request/response flow, both payment methods, expected behavior, idempotency, and business outcome. An agent has all necessary context to invoke it correctly.

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

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

Schema coverage is 100%, but the description enriches each parameter's meaning: it explains 'x_payment' is only for step 2 and its base64 JSON payload format, clarifies the exclusivity of sermon_id vs bundle_id, and instructs to omit x_payment on step 1. This goes far beyond the schema descriptions.

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

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

The description clearly states the tool's function: 'Pay for a paid sermon or bundle per-call in USDC on Base using the x402 protocol.' It names the specific verb (pay), resource (sermon or bundle), payment method (USDC on Base), and differentiates from siblings by emphasizing the agent-native, no-account-per-call approach.

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 explains when to use this tool—'per-call' with 'no SoapBox account, API key, or prepaid credits required'—contrasting with account-based alternatives. It also provides a detailed two-step usage protocol, so an agent knows exactly how to invoke it in sequence versus 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?

The description goes beyond annotations by disclosing revenue split (70/30), classifying the transaction as a content sale rather than a donation, and confirming that it grants access to every sermon. While the idempotentHint is already in annotations, the description reinforces it and adds valuable financial and access 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?

The description is concise yet information-dense, covering all key aspects (action, payment, discovery, revenue split, idempotency) without redundancy. Each sentence earns its place, and the structure is clear and front-loaded.

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

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

For a single-parameter purchase tool, the description is remarkably complete: it explains what a bundle is, how to acquire it (credits or x402), how to find it, the financial terms, and idempotency. There is no output schema, so return format is not required. The description leaves no obvious gaps.

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

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

The schema fully describes bundle_id, including its origin as product_id from browse_catalog. The description adds marginal value by referencing the use of bundle_id in pay_with_x402, but this is more about an alternative flow than the parameter's semantics for this tool. With 100% schema coverage, 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 clearly states the verb 'buy' and the resource 'bundle (a sermon series)', and explains it grants access to every sermon. It distinguishes itself from sibling purchase_sermon by focusing on bundles and mentions how to find bundles via browse_catalog. The explicit reference to 'same terms as purchase_sermon' further differentiates it.

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

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

The description provides explicit guidance: use this tool to purchase bundles with prepaid credits; if no credits, use pay_with_x402 with the same bundle_id. It also directs users to browse_catalog for discovery. This gives clear usage context and alternatives.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds valuable context: merchant-of-record fee split (70/30), the fact it's a sale not a donation, that get_sermon will then return the full transcript, and that purchases are idempotent (no double-charge). This goes well beyond what annotations declare, giving clear behavioral expectations 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?

The description is front-loaded with the main purpose and every sentence earns its place: fee structure, post-purchase behavior, idempotency, credit insufficiency handling, and the x402 alternative. It is dense but not bloated, with no redundant repetition of schema or annotations.

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 single-parameter schema, no output schema, and modest annotations, the description covers all necessary context: what the tool does, how payment works, what happens after purchase (get_sermon returns transcript), failure modes (insufficient credits), and alternative payment routes. It paints a complete mental model 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?

The input schema already fully describes sermon_id with examples and explanation ('The paid sermon to purchase, e.g. a sermon_id from search_sermons or browse_catalog'). Schema coverage is 100%, so the description adds little parameter-specific meaning beyond the schema. The description mentions the sermon_id in the context of x402, but that's not new semantic detail for the parameter itself.

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

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

The description opens with a specific verb+resource: 'Buy permanent access to a paid sermon using your prepaid marketplace credits.' This clearly states what the tool does and uniquely positions it among siblings like get_sermon (which retrieves after purchase) and pay_with_x402 (an alternative payment method).

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

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

The description provides explicit when-to-use and when-not-to-use guidance, including alternatives: 'If you have insufficient credits, check get_credit_balance and top up. No key / no credits? Pay per-call in USDC on Base via x402 instead — call pay_with_x402 with this sermon_id.' It also differentiates from donations, clarifying this is a content sale.

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 valuable context beyond this: it returns an impartial rating, score, summary, and doctrinal loci, and explicitly states it is analytical and not proselytizing. These details clarify the tool's tone and output, going beyond the structured annotations.

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

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

The description is concise, consisting of two focused sentences. The first states the core purpose, and the second covers output, impartiality, and access requirements. Every sentence contributes meaningful information without redundancy.

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

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

Despite having no output schema, the description clearly enumerates the return values (rating, score, summary, loci) and notes the impartial, analytical nature. It does not mention potential errors or limitations, but for a read-only, non-destructive tool, the description is sufficiently complete for an agent to use it effectively.

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 both parameters fully described and examples provided. The description does not add additional parameter-specific semantics beyond what the schema already offers, so it relies on the schema to carry the parameter 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 assesses doctrinal alignment with named Christian traditions, using specific verbs and resources. It distinguishes itself from siblings like verify_scripture by focusing on tradition-based evaluation rather than scriptural verification.

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

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

The description provides clear context on the tool's appropriate use: it's analytical, not proselytizing, and requires no key, implying open access. However, it does not explicitly mention when not to use it or mention sibling alternatives, falling slightly short of full 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?

Discloses that only consented, published sermons are searchable and describes the return format (ranked excerpts with title, church, speaker, scripture reference, start-time). This goes beyond the readOnlyHint annotation, adding material context about data provenance and output structure without contradiction.

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

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

Four sentences with each serving a distinct purpose: core function, return fields, usage recommendation, and consent constraint. No redundant or filler content; information is front-loaded with the verb and resource.

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

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

No output schema is provided, so the description compensates by detailing exact return fields and the start-time for citation. It also covers the data source scope and consent. This is complete for a search tool, leaving no major informational gaps.

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

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

The input schema already provides full descriptions for all three parameters (query, church_id, match_count) with examples and constraints. The description's mention of 'semantic search' adds no new parameter-level meaning beyond what the schema states, 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 clearly states the tool 'semantically search real sermons on SoapBox' with a specific resource (opted-in sermon transcripts) and output (ranked excerpts with metadata). It differentiates from siblings like get_sermon (retrieving a specific sermon) and find_churches (searching churches) by focusing on topical sermon search.

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 the use case: 'Use this to find what churches are actually preaching on a topic.' It also mentions the consent constraint. However, it does not explicitly say when not to use it or name alternative tools, 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 provide readOnlyHint=false and destructiveHint=false, and the description adds meaningful context: the need for a scoped consent token, that the action is on behalf of a user, and that it returns a prayer_id for tracking. It stops short of discussing side effects or reversibility, but given annotation coverage, it is sufficiently transparent.

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

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

Three sentences, each earning its place: action, auth requirement, return value + follow-up. It is front-loaded with the primary purpose and avoids redundancy or filler.

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

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

For a create-type tool with no output schema, the description covers the essential context: what it does, what's needed, what it returns, and what to do next. It doesn't explain edge cases like is_private handling or idempotency, but annotations and schema cover those sufficiently. The description is complete for typical 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 description coverage is 100%; each parameter (content, is_private, consent_token) already has a clear description. The tool description adds no additional parameter-level meaning beyond what's in the schema, so baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Post a prayer request to SoapBox's prayer wall.' It adds crucial nuance: 'ON BEHALF OF A USER' and 'so their community can pray for it.' This clearly distinguishes it from siblings like check_prayer_status and find_churches.

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 explains the key prerequisite: 'Requires the user's consent_token ... an API key alone is not enough to act for a user.' It also directs the user to the appropriate follow-up: 'use check_prayer_status to see how many are praying.' This explicitly names an alternative for a related task.

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

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

Beyond the annotations, the description discloses important behavioral traits: results are cached (consistent with idempotentHint), requires an API key, and notes that audio generation has real cost. This adds valuable context that annotations alone do not convey and aligns with the non-read-only, non-destructive hints. No contradiction found.

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

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

Four sentences, each with a clear purpose: the first states the core function and output, the second covers the primary input parameters, the third notes caching behavior, and the fourth explains the API key requirement and cost. No filler or redundancy; front-loaded with the main purpose.

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 no output schema, the description tells you exactly what to expect ('playable audio URL'), covers the required input (text), key optional parameters, caching, auth, and cost. All five parameters are well-specified in the schema, and the description provides the missing operational context (cost, key) needed for a complete usage picture.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters in detail. The description adds only a small framing benefit (e.g., '50+ languages', 'optional voice/gender') but does not provide new semantic details beyond the schema's own parameter descriptions. This matches the baseline for complete 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 uses a specific verb ('Generate') and resource ('spoken-audio / text-to-speech') and clearly states the output ('playable audio URL'). It also scopes the content domain ('verse, prayer, or devotional'), distinguishing it clearly from sibling tools like get_verse or search_sermons, which are text-based.

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

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

It provides clear context on how to use the tool by mentioning the BCP-47 language tag and optional voice/gender parameters. The cost and API key requirement give practical usage guidance, though it does not explicitly name alternatives or state when not to use this tool (no TTS alternatives exist among siblings anyway).

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?

With annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds value by detailing what the tool returns: whether it matches a real verse, canonical KJV reference + text, a confidence score, and attribution correctness. This gives the agent a clear expectation of the tool's behavior beyond the generic read-only hint.

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 core purpose, and each sentence earns its place. It avoids fluff while packing in the essential behavioral details and usage guidance.

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

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

Given the absence of an output schema, the description compensates by listing the key return elements (real verse match, KJV reference + text, confidence score, attribution correctness). The tool is simple (2 params, read-only), and the description covers the purpose, usage, and outputs thoroughly, making it complete for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100% for both parameters, providing a baseline of 3. The description adds meaning beyond the schema by explaining the purpose of the optional reference parameter ('if you pass a claimed reference — whether the attribution is correct') and by emphasizing that the quote is verified against real Scripture. This enhances the semantic understanding of the parameters.

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: 'Verify whether a quote is real Scripture and cited correctly (anti-hallucination).' This uses a specific verb (verify) and resource (quote/Scripture), and distinguishes it from sibling tools like get_verse by focusing on verification rather than retrieval.

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

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

The description provides explicit when-to-use guidance: 'Use this before presenting any Bible quote to avoid misquotes/fabrications.' It also explains the conditional use of the reference parameter ('if you pass a claimed reference'). It doesn't explicitly mention alternatives or when-not-to-use, 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.