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 mark readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds value beyond annotations by stating the return shape ('id, title, church, and price'), the pre-payment role ('Then pay for one with pay_with_x402'), 'No key required', and the open-ended future catalog expansion.

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

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

Three short sentences front-load purpose, then return fields, then the payment next step, filters, and auth requirement. Every sentence earns its place and there is no repetition of the title or obvious 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?

With no output schema, the description correctly states the key return fields, which is essential. It also covers auth, filter options, and the payment hand-off. It does not discuss empty results or pagination behavior, but limit is already in the schema, so this is sufficient for a low-complexity read tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only gestures at 'Optional church_id and text filter,' restating q and church_id without adding format, sort, or interaction semantics beyond the schema. It provides no meaningful extra 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 verb 'Browse' plus resource 'purchasable faith-content products on SoapBox' states exactly what the tool does. Mentioning the returned fields and the current scope ('currently consented sermons') separates it from search/get-sermon siblings. The purpose is unambiguous even without explicit sibling contrast.

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 the use case—browse the catalog, then pay with pay_with_x402—but gives no explicit when-to-use or when-not-to-use guidance versus search_sermons or get_sermon. It provides useful context ('currently consented sermons; bundles coming') but no exclusion criteria. Adequate but relies on inference.

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

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

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 carry only generic hints (readOnlyHint=false, destructiveHint=false), so the description carries the full behavioral burden and discharges it thoroughly. It discloses the non-posting preview behavior of the first call, the `problems` flag list, the crisis gate that holds posting until `crisis_acknowledged: true` while explicitly clarifying 'This is not a refusal,' and the hard ethical boundary 'YOU DO NOT PRAY.' An agent knows exactly what side effects each call has.

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

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

The description is long but every paragraph is load-bearing: purpose+routing, two-call mechanics, textual-fidelity rules, the do-not-pray boundary, and crisis handling. Critical procedural information is front-loaded in the first two paragraphs, and paragraph breaks map cleanly to distinct concerns. Nothing reads as filler, and each sentence earns its place given 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?

With no output schema, the description must explain return values itself, and it does: 'you get back `will_post`, the exact text and visibility, plus `problems`' and 'the response carries crisis resources.' It covers the full lifecycle — preview, confirmation, posting, crisis gate, follow-up status check — and the prohibitions an agent must observe. For a 5-param two-phase tool with ethical constraints and no output schema, nothing needed for correct invocation 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% with individually strong parameter descriptions, so the baseline is 3. The tool description adds genuine protocol context beyond the schema: it explains why `confirmed` exists (two-call commit flow), when `crisis_acknowledged` becomes relevant (only after a first-call crisis response), and why `content` must be verbatim ('These are their words'). The description complements rather than repeats the schema, though the schema alone already carries param-level meaning well.

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

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

The opening sentence names a specific verb ('help a member put something into words and post it') and a specific resource ('their church's prayer wall'). It then distinguishes itself explicitly from its closest sibling: 'Use this rather than submit_prayer_request whenever you helped them word it.' An agent can immediately tell what this tool does and which sibling it is not.

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

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

The description gives an explicit routing rule versus submit_prayer_request, then a step-by-step protocol: call once without `confirmed` to get `will_post`, show it to the member, call again with confirmed: true. It also directs the agent to the correct follow-up tool ('After posting, check_prayer_status tells them how many PEOPLE are praying') and covers the crisis-acknowledgment path. When-to-use and when-not-to are fully specified.

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

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

Annotations already mark this as read-only and non-destructive. The description adds valuable context: it specifies that only public directory data is used, excludes personal contact info, and details the return fields (name, denomination, location, website, distance, SoapBox membership with community id). This goes 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?

Two sentences with zero filler. The first sentence states the purpose, and the second lists return fields and data scope. The description is front-loaded and every word earns its place.

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

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

For a tool with 5 parameters and no output schema, the description compensates by listing return fields and clarifying data scope (public, no personal info). It doesn't explain the limit ranking or radius default, but those are in the schema. It is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions 'optional radius, denomination filter' but does not add meaning beyond what the schema already documents for each parameter. It adds no extra semantics like units or formatting that aren't already in the schema.

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

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

The description states a specific verb (Find) and resource (churches near a location from SoapBox's public directory), which clearly differentiates it from sibling tools like find_churches_preaching_on or search_sermons. It immediately conveys the tool's unique function.

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 stating the task ('Find churches near a location') but does not explicitly mention when to prefer it over siblings or provide exclusions. It lacks direct guidance on alternatives, so the agent must infer from the purpose.

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 directly contradicts the annotation openWorldHint=false by stating a church's absence is not evidence it never preaches on a topic, an open-world caveat. This is a serious inconsistency; otherwise the description would have earned a high score for its rich caveats about opt-in coverage and non-endorsement.

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

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

The description is longer than average but well-structured with a clear purpose statement, a dedicated 'TWO THINGS' block, and a closing pairing note. Each sentence adds value: no filler, and the most important caveats are front-loaded.

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

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

Despite the annotation contradiction, the description alone covers what the tool returns (matched sermons per church, closeness, excerpt, timestamp), the opt-in limitation, the ranking semantics, the non-endorsement interpretation, and auth requirements ('No key required'). With no output schema, this is a complete operational guide.

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 three parameters. The description adds no parameter-specific semantics beyond that, though it does mention ranking over closest-matching passages, which is subtly relevant to the limit param. 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 the exact question the tool answers and specifies the verb 'searches' plus the resource 'consented sermons', then clarifies the group-by-church behavior. This distinguishes it from siblings like search_sermons 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 states a clear use case ('someone looking for a church home...') and explicitly recommends pairing with find_churches. It does not name when not to use it or alternatives like search_sermons, but the grouping-by-church distinction is enough for an agent to select 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?

Beyond the readOnlyHint=true annotation, the description adds key behavioral context: the tool reports rate limits, not affordability; the old marketplace-credit wallet is retired; the returned marketplace_credits_cents is always 0 and must not be interpreted as a funds signal. This goes well 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 primary purpose is front-loaded in the first sentence, and each subsequent sentence earns its place by preventing a specific misreading: purchase gating, legacy naming, and the always-zero funds field. Despite its length, none of the content is redundant.

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

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

For a zero-parameter read-only status tool with no output schema, the description covers what the tool reports, what it doesn't mean, when to use an alternative, and how to interpret legacy fields. Nothing an agent needs to call it correctly is missing.

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

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

The input schema is empty (0 parameters) and schema coverage is 100%, so there are no parameter semantics to add. Per the baseline for zero-parameter tools, 4 is appropriate; no parameter documentation is needed.

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

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

The description names a specific verb and resource: 'Report this API key's tier and daily rate limit,' and clarifies what it is not ('not what you can afford'). This differentiates it from payment/purchase tools like pay_with_x402 and from the legacy get_credit_balance semantics.

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 gives a when-not case: 'Nothing here gates a purchase,' and routes purchases to the sibling pay_with_x402, noting that alternative needs no key or balance. It also warns against reading marketplace_credits_cents as 'out of funds,' preventing 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?

The description discloses several important behaviors beyond the annotations: it requires an API key and incurs cost per character (a side effect not implied by readOnlyHint=false), it falls back to text if no voice exists for the language, it always speaks Scripture in English (KJV) and never translates it, and it outlines a two-step flow. These are critical for an agent to call the tool correctly and to manage member expectations. The annotations only provide idempotentHint and destructiveHint, so the description carries the full burden, and it does so thoroughly.

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 relatively long (about 150 words) but every sentence carries necessary information for a tool with seven parameters and a complex two-step workflow. It is structured logically: purpose first, then language handling, then scripture rule, then the two-step process. While it could be tightened slightly, the length is justified by the tool's complexity, so it is concise relative to the required nuance.

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

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

Given the tool's complexity (7 parameters, no output schema, but significant behavioral nuance), the description is very complete. It explains the return behavior ('returns audio URLs alongside the text', 'step 1 returns translate_this', 'you get both audio files back' for step 2), the cost implications, language fallback, and scripture constraints. An agent could confidently invoke this tool without needing additional clarification from the schema or 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?

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond the schema. It explains the relationship between consent_token and language, the fallback order, the two-step usage of reflection_text (only for non-English, step 2), and what translate_this is. It also warns about the scripture constraint for the language parameter. This contextual information is essential for correct parameter usage and is not present in the schema.

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

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

The description immediately states the tool's purpose: 'The same daily devotional, SPOKEN' – clearly indicating an audio version of the daily devotional. It specifies the resource (devotional) and the action (get audio), and implicitly distinguishes itself from the sibling get_daily_devotional by contrasting the spoken format with presumably the text version. It also mentions 'Returns audio URLs alongside the text' which further clarifies what it delivers.

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 usage context: it is for members who prefer listening or read little, and it explains when to use the consent_token versus the language parameter. It also details the two-step process for non-English members. However, it does not explicitly name alternatives (like get_daily_devotional) or state when not to use this tool, so it falls slightly 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?

While annotations already declare readOnlyHint and destructiveHint, the description adds meaningful behavioral context: it requires no API key, is deterministic (same date → same reading), and explicitly states it does not pray on the member's behalf or claim divine knowledge, pointing to pastoral care. This goes beyond the annotations and clarifies what the tool will and will not do.

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

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

The description is longer than average but every sentence serves a purpose, and the core purpose is front-loaded. The 'two things this is not' section is clearly structured and high-value, preventing common misuses. It could be trimmed slightly, but the density of useful information justifies the length.

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 fully explains the return contents and behavior, including the absence of auth, deterministic outputs, and the intended pastoral posture. For a read-only devotional builder, nothing crucial is missing; an agent can call it correctly and set expectations.

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

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

Schema coverage is 100%, so the schema already explains both parameters. The description mentions the season-aware selection but does not explicitly link the 'reference' parameter to overriding the seasonal choice; that is only in the schema. It adds marginal value by confirming the devotional's seasonal nature, but no extra parameter-level detail beyond the schema.

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

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

The description states a specific verb ('build'), a resource ('a season-aware daily devotional'), and enumerates the exact outputs (liturgical season/colour, KJV passage, three reflection questions, prayer prompt). It also explicitly distinguishes itself from the lectionary and from homilies, which differentiates it from siblings like get_lectionary and get_sermon.

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 clearly states when not to use this tool (it is not the lectionary, not a homily/spiritual direction) and gives the context that it is a study aid. It does not explicitly name alternative tools but the exclusions effectively guide an agent away from misapplying it. The determinism note ('same date always returns the same reading') adds a relevant usage condition.

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 and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: the consent token requirement with 'giving:read' scope, the fact that the reader is keyed to the member and cannot be used for anyone else, the handling of refunded/charged-back gifts (counts_toward_total false), the distinction between amount_cents and gross_amount_cents, and the inclusion of anonymous gifts. It also explicitly warns against presenting the output as a tax receipt. This is rich, non-obvious behavioral disclosure.

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

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

The description is longer than average, but every sentence earns its place. It front-loads the core purpose in the first sentence, then layers critical constraints (not a tax receipt, own data only, refund handling, anonymous gifts). The structure is logical: purpose → usage → exclusions → edge cases. It is not bloated; the length is justified by the sensitive financial data and the need to prevent misuse. It loses one point only because it could be tightened slightly without losing meaning.

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

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

For a read-only financial data tool with no output schema, the description is remarkably complete. It covers what data is returned, the auth requirement, the scope limitation, the tax-receipt caveat, refund/chargeback semantics, anonymous gift handling, and the all_churches behavior. An agent has everything it needs to call the tool correctly and to avoid misrepresenting the output. The absence of an output schema is compensated by the detailed field enumeration in the first sentence.

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 four parameters well. The description adds meaningful context beyond the schema: it explains the consent token's scope requirement, clarifies that year is counted in each church's time zone, and explains why all_churches=true is needed for reconciling a tax year. It doesn't add syntax details, but the schema already covers those. The description's added context about the token's keying to the member and the all_churches privacy consideration earns a 4 rather than a baseline 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 states a specific verb ('Fetch'), a specific resource ('the member's OWN record of what they gave in a year'), and enumerates the exact data fields returned (every gift, church, date, amount, fund, totals per currency). It also clearly distinguishes this from a tax receipt and from sibling tools like give_to_church. The scope is unambiguous: 'Their own data only.'

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

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

The description gives explicit when-to-use guidance: 'Use this to help them check their records, reconcile what they think they gave, or find a gift they are looking for.' It also provides explicit when-not-to-use guidance: 'Do not use it to estimate what they can afford, compare them to anyone, suggest an amount to give, or build any kind of giving-capacity picture.' It even tells the agent to direct the member to their church for the actual tax statement, which is a clear alternative.

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

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

The description adds substantial behavior beyond the readOnlyHint annotation: opt-in visibility, not-found behavior, paid vs. free transcript handling, price return, and the payment follow-up. This is exactly the kind of contextual behavior an agent needs to manage user expectations and next actions.

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, all necessary, with the core action and identifier source first. There is no filler or repetition of schema details; the payment and opt-in caveats are delivered efficiently.

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-sermon fetch with no output schema, the description covers the important return cases: metadata, transcript, price, and not-found. It also explains the permission model and the payment pathway, making the tool's behavior predictable for an agent.

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

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

Input schema coverage is 100%, so the schema already documents both parameters. The description adds only a small amount of context ('optionally' and the payment workflow) but does not materially extend parameter meaning beyond what the schema states.

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

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

The description uses a specific verb ('Fetch') and names the exact resource ('full metadata and optionally the transcript for ONE sermon by its id'). It clearly positions the tool as a single-item lookup rather than a search, distinguishing it from siblings 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?

It explains that the id is 'typically a sermon_id returned by search_sermons', which gives the agent a clear prerequisite and data source. It also routes paid-transcript use to pay_with_x402. However, it does not explicitly state when to avoid this tool in favor of a search or other sermon-related siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so 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?

Annotations already mark the tool read-only and non-destructive, and the description adds substantial behavioral context beyond that: deterministic blank patterns across calls, LCS-based alignment so early word drops don't cascade, KJV italic words and punctuation being excluded from scoring, stripped Psalm titles, the drill-on-miss feedback loop, and next_level gating on clean recall. Nothing in the description contradicts the readOnlyHint.

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

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

The description is long but every paragraph carries operational information needed to invoke the tool correctly, and the purpose and mode split are front-loaded. It loses a point for partial redundancy, since the level-hiding semantics in the description roughly restate the schema's level parameter description.

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 there is no output schema, the description carries the full burden of explaining return values, and it does so for both modes: blanked verse for drills, and accuracy/missed/added/first_divergence for checks. Combined with annotations covering the safety profile, nothing an agent needs to select a mode, set a level, and interpret a response is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the determinism property for level ('same reference and level always produce the same blanks'), the italic-word scoring rule for attempt, and the Psalm-title stripping for reference. Some level detail is redundant with the schema's own parameter description, but the added nuances elevate it above baseline.

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

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

The first sentence states a specific verb and resource ('Help a member learn a verse by heart') and immediately names the two operating modes, DRILL and CHECK. The function is concrete enough that an agent can distinguish it from siblings like get_verse (plain retrieval) and verify_scripture (text/reference checking) even though no sibling is named.

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

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

The description gives explicit mode-selection guidance: 'DRILL (omit `attempt`)' vs 'CHECK (pass `attempt`)', plus explicit don'ts ('must not be quizzed', 'Present this as memory work, not as a test of faith'). It does not, however, name sibling alternatives or state when this tool should NOT be chosen over get_verse or verify_scripture, so it stops short of full when/when-not coverage.

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

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

Even though annotations already indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description adds substantial behavioral context beyond those hints: the payment-as-credential model, no account/API key required, merchant-of-record fee split, exact-amount enforcement, signature requirement and rationale, idempotency per tx hash, and acceptance of EIP-3009 facilitator payments. It fully discloses the payment flow and consequences of incorrect amounts.

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

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

The description is long but every sentence earns its place given the protocol's complexity. It is front-loaded with purpose and key differentiators, then procedurally explains the two steps. It loses one point for being a dense single paragraph that could be structured more explicitly (e.g., numbered steps), but it is not verbose or padded.

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, the description is complete: it describes the full two-step workflow, what step 1 returns (HTTP-402 payment requirements), what to send, how to sign, what the server checks, and that the return is a transcript. With no output schema, it covers the return value sufficiently. Annotations cover idempotency and side effects, so nothing essential 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?

Though schema description coverage is 100%, the description adds crucial meaning to the parameters: it explains sermon_id vs bundle_id mutual exclusivity, the step-1 vs step-2 usage of x_payment, the exact payload shape (base64 of {"txHash":...,"signature":...}), and that EIP-3009 authorizations are also accepted. This goes well beyond the schema's basic field descriptions and directly aids correct invocation.

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

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

The description states a specific verb+resource: 'Pay for a paid sermon or bundle per-call in USDC on Base using the x402 protocol.' It also distinguishes from siblings by noting it is the only tool that buys SoapBox faith content, and contrasts with give_to_church (sale vs donation). This leaves no ambiguity about what the tool does or how it differs from alternatives.

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

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

The description explicitly says when to use this tool versus alternatives: it is the only way to buy faith content, mentions retired prepaid-credit tools and the browser fallback, and differentiates from donations. It also provides a clear two-step usage procedure with exact guidance on when to omit x_payment (step 1) and when to include it (step 2), including warnings about exact amounts and re-running step 1 if time passes.

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?

The description significantly expands on the readOnlyHint annotation by detailing exactly what is read (public-domain Scripture, computed calendar, opted-in sermons), that it grants no special access, has no role check because there is nothing private, and warns that content must be checked before use. This is rich, non-contradictory transparency beyond the structural annotation.

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

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

The description is structured into three focused paragraphs: core purpose, read-only behavior/access, and usage boundary. The key info is front-loaded in the first sentence. It is somewhat verbose, but each sentence serves a distinct purpose (explaining what is included, why no auth is needed, and how results should be used), so the length is justified for the tool's scope.

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 no output schema, the description enumerates exactly what is returned (liturgical day, KJV passages, Strong's entries, other churches' sermons) and explains access and safety. The only notable gap is the absence of an explicit description of the output structure or formatting, but the itemized list gives the agent a strong mental model of what to 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?

Schema description coverage is 100%, with each parameter already described (date format, focus natural language, Strong's format, reference format). The description only mentions the same concepts in prose ('KJV passages', 'Strong's lexicon entries') without adding new meaning or format details. Baseline 3 is appropriate because the schema carries the semantic load.

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 ('assemble') and names the resource ('research kit') with its exact components: liturgical day, KJV passages, Strong's entries, and other churches' sermons. It explicitly distinguishes itself from siblings by saying 'One call instead of five' and clarifies what it is NOT (draft, outline, advice), leaving no ambiguity about its function.

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

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

The description gives clear context for when to use the tool: when assembling multiple research pieces for preaching/teaching, and emphasizes efficiency ('one call instead of five'). It also provides an exclusion by stating it is NOT a draft/outline/advice. However, it does not explicitly name the alternative dedicated tools (e.g., get_verse, lookup_strongs) or state 'if you need only one component, use that tool,' leaving the differentiation partially implicit.

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 readOnlyHint annotation, the description discloses key behaviors: sections span the WHOLE recording, timestamps/references/access check are provided, and paid sermons return HTTP 402 until purchased. It also sets role boundaries by stating 'ORA Assistant does not teach and does not speak for the preacher or the church.' This significantly enriches the agent's understanding of side effects and constraints without contradicting 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 long but every sentence earns its place: it front-loads the purpose, then covers output contents, agent responsibility, verification, payment, and presentation style in a logical order. There is no redundant or filler text, and the structure supports a quick scan of the key points.

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, read-only tool with no output schema, the description covers everything an agent needs: return value structure (sections with quotes/timestamps, references, question scaffold), error handling (HTTP 402), prerequisites (pay_with_x402, verify_scripture), and usage boundaries. No critical information is missing for correct invocation and result interpretation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that 'sections' controls how many sections are pulled and that 'sermon_id' comes from search_sermons or find_churches_preaching_on, which matches the schema. It does not add new parameter-level semantics beyond the schema, so a 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 'Turn one sermon into material a small group can work through,' which clearly states a specific verb, resource, and outcome. It further distinguishes itself from siblings like get_sermon, sermon_prep_kit, and search_sermons by detailing the unique deliverables: timestamped sections, extracted Scripture references, and a discussion scaffold. This leaves no ambiguity about the tool's 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 strong usage context: it mentions the prerequisite of paying for paid sermons with pay_with_x402, the need to verify references with verify_scripture, and the constraint that only opted-in sermons are available. It does not explicitly name alternative sibling tools or state when not to use this tool, but the conditions and workflow are clear enough for an agent to select it appropriately.

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

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

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.