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 declare readOnlyHint=true and destructiveHint=false, so the tool is a safe read. The description adds valuable context beyond annotations: it discloses that a valid consent_token is required (authorization constraint) and that results are restricted to the user's own prayers. It also mentions the answered status field. It does not detail response format or error behavior, but for a read-only tool with this level of annotation coverage, the added context is solid.

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 states the core action, the prerequisite, and the scoping rule with zero waste. Every clause earns its place, making it efficient for an agent to parse quickly.

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 two well-documented parameters and no output schema, the description covers the essential aspects: what it does, the prerequisite (consent_token), and the data it returns (count and answered flag). It does not describe the response format explicitly, but the description implies the key fields. No significant information an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% – both prayer_id and consent_token have descriptive entries in the schema. The description does not add new semantics beyond what the schema already provides, though it reinforces the consent_token requirement. Since the schema carries the full parameter documentation, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Check how many people are praying for a prayer request previously submitted for a user (and whether it's been marked answered).' It uses a specific verb (check), names the resource (prayer status), and distinguishes itself from the sibling submit_prayer_request by referencing 'previously submitted'. The scope constraint ('only returns status for that user's own prayers') further clarifies what it does.

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

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

The description provides clear context for when to use the tool: 'previously submitted' implies it should be used after a prayer request has been created via submit_prayer_request. It also specifies a prerequisite ('Requires the same user's consent_token') and the scoping rule. However, it does not explicitly name alternatives or state 'use this instead of X', though the sibling list makes the pairing obvious.

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

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

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?

The annotations declare readOnlyHint=true and destructiveHint=false, but the description goes beyond by detailing the consent requirement, the token binding to the agent, the 24-hour token lifecycle, and the explicit exclusion of private prayers/journal. It also warns about authorization errors. This is rich behavioral context that 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 well-structured, with the main purpose front-loaded, followed by consent requirements and privacy scoping. While the parameter description is comprehensive, it is slightly lengthy but still focused. Every sentence serves a clear purpose, balancing conciseness and necessary detail.

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 it has a single parameter with high schema coverage and no output schema, the description fully compensates by explaining the exact data returned and the authorization failure case. There is no ambiguity about what the tool does, what inputs it needs, and what the agent should expect.

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 describes the consent_token with examples and scope, but the description adds value by embedding the full token lifecycle and privacy guarantees. It reinforces what the token is and its constraints, complementing 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 purpose: to read a user's portable faith context for personalization, with explicit consent. It distinguishes this from siblings like get_verse or get_sermon by focusing on the user's profile data. The description also specifies what is included (denomination, language, journey, interests) and what is excluded (praises, journal).

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

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

It explicitly states when to use it: to tailor tone, tradition, and language. It also provides clear constraints: requires the user's consent_token with specific scope, and clarifies that it returns only declared profile, not private data. This gives the agent precise conditions for invocation and what to expect.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true), the description discloses the passthrough mechanism ('SoapBox takes no cut'), rejection on cap violations, the need for a stable idempotency_key, the mandatory user confirmation, and user notification. These behavioral specifics are not inferable from annotations and substantially aid correct invocation.

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 core action, then layers prerequisites, rejection conditions, idempotency, and safety guidance in a logical order. Every sentence carries practical, non-redundant information; no filler, no repetition of annotation values. Its length is justified by 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?

For a money-moving tool with no output schema, the description covers prerequisites (token, card), failure modes (caps), idempotency, user-confirmation duty, and notification. It does not specify the response/return payload or what happens when a saved card is missing, but these are minor given the schema and annotations cover the main operational 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?

Schema coverage is 100%, so the baseline is 3. The description mostly repeats schema facts, e.g., 'Amounts are in the smallest currency unit (cents)' and 'Pass a stable idempotency_key to avoid double-charging on retries' mirror the parameter descriptions exactly. It adds no new parameter-level insight beyond what the schema already communicates.

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

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

The description starts with a specific verb-resource pair ('Make a one-time donation to a church') and adds the crucial 'ON BEHALF OF A USER' scope, which distinguishes it from generic payment tools. It also mentions the spending-cap constraint and the giving:write consent scope, making it unmistakable among siblings like purchase_sermon or pay_with_x402.

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

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

The description gives clear preconditions: a consent_token with 'giving:write', pre-authorized caps, and a saved card. It also instructs the agent to confirm with the user before calling. However, it never explicitly names alternatives or states 'use this for giving, not purchasing', so it stops short of the explicit routing in the strongest examples.

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?

The description goes far beyond the annotations, detailing the two-step 402 flow, the requirement to send exactly maxAmountRequired, refusal of other amounts, the mandatory signature, idempotency per tx hash, and accepted EIP-3009 gasless payments. This is rich, accurate behavioral disclosure with no contradiction against 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?

Although long, the description is well structured and every sentence earns its place. The core purpose is front-loaded, followed by a numbered two-step flow, clear payment constraints, and the reason the signature is required. The length is justified by the complexity of the protocol.

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 payment tool with no output schema, the description is remarkably complete: it covers the full call sequence, exact payment amount and network, recipient address, signing requirements, idempotency, and an alternative payment path. An agent has enough information to invoke both steps correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful protocol-level meaning: exactly one of sermon_id or bundle_id is required, x_payment must be omitted on step 1, and step 2 requires a base64 payload containing a signed tx hash as described. This goes beyond the schema's property descriptions without being redundant.

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 and resource: paying for a sermon or bundle per-call in USDC on Base using x402. It differentiates this rail from SoapBox's account/credit-based flow by explicitly saying no account, API key, or prepaid credits are required.

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 makes the appropriate context clear: agent-native per-call payments without SoapBox credentials, with a precise two-step protocol. It does not explicitly name sibling alternatives like purchase_sermon or purchase_bundle and state when to choose them instead, so it stops short of full 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?

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?

With all annotation hints set to false (readOnly, openWorld, idempotent, destructive), the description carries the burden of behavioral disclosure. It excels by revealing critical traits: the token binding to the first agent, the 24-hour expiry, the requirement for prayer:write scope, and the return of a new prayer_id. It also implies non-idempotency through 'Post' and 'Returns the new prayer_id'. This is substantial and goes beyond what annotations 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 two sentences, but every part earns its place. The first sentence front-loads the primary action and its on-behalf-of nature. The second packs the consent-token requirement, the API-key limitation, the return value, and a pointer to the follow-up tool. No redundant phrases, perfectly structured for quick comprehension.

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

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

Given that this is a mutation tool with no output schema, the description is nearly complete. It states the action, prerequisites, token constraints, return value, and a follow-up tool. It does omit specifics on error handling beyond token issues and does not describe any side effects like visibility timing, but given the schema already handles parameter details, this is adequate for an agent to invoke it correctly. A slight gap is the lack of explicit behavioral notes for is_private, but that's in the schema.

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 description coverage is 100% for all three parameters, with each having its own detailed description (e.g., consent_token explains scope, binding, and expiry). The tool description adds only the return value as context, not per-parameter nuances. Since the schema already documents the parameters thoroughly, the description's contribution is minimal, matching the baseline of 3.

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

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

The description clearly states a specific action ('Post a prayer request'), the resource ('SoapBox's prayer wall'), and the scope ('ON BEHALF OF A USER'). It also distinguishes itself from the sibling check_prayer_status by mentioning the return of a prayer_id and directing to that tool for follow-up, which differentiates its 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?

The description gives a clear prerequisite: it requires a user's consent_token with the 'prayer:write' scope and explicitly notes that an API key alone is insufficient. This serves as an implicit condition for when to use the tool. It also recommends check_prayer_status for post-creation status checks. However, it does not explicitly state when not to use it or name alternative creation tools, though the token requirement effectively bounds usage.

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.