SoapBox Faith

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

Without annotations, the description carries full burden. It discloses that ORA is a study aid, not a substitute for professional help, and returns KJV-based answers. Could mention rate limits or input constraints, but the disclaimer adds important behavioral context.

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

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

Three sentences, front-loaded with main action, then usage guidance. No fluff, each sentence 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?

Despite no output schema, the description fully explains return values (grounded answer with citations). Along with usage guidelines and behavioral notes, it is complete for this tool's simplicity.

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

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

Schema coverage is 100% with a single parameter 'question' already described as 'The Bible or faith question to ask ORA (max 1000 chars).' Description adds no new parameter information beyond the schema, so baseline score applies.

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

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

The description clearly states the tool answers Bible/faith questions via ORA and returns cited KJV passages. It distinguishes from sibling 'get_verse' by specifying this is for explanatory/study questions.

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 provides when to use this tool (explanatory/study questions) and when not (personal crises, pastoral/medical needs, where it directs to trusted professionals). Also contrasts with sibling 'get_verse'.

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?

No annotations are provided, so the description must fully convey behavior. It discloses that no key is required, returns specified fields, and has optional filters. However, it lacks details on pagination (limit param is mentioned but default not stated in description), sorting, error handling, or behavior when no results.

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 (4 sentences), front-loaded with the core purpose, and each sentence adds distinct value: scope, return fields, purchasing action, optional filters, and access requirement.

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

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

The description covers the essential aspects: what it does, what it returns, how to proceed to purchase, and optional filters. It lacks some details like result ordering or error handling, but given the simplicity of the tool and full schema, it is mostly complete.

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 describes all three parameters. The description merely repeats 'Optional church_id and text filter' without adding new meaning or usage context beyond what the schema provides.

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: browse purchasable faith-content products on SoapBox, specifying current (sermons) and upcoming items. It distinguishes itself by mentioning 'Then buy with purchase_sermon', linking to a sibling for purchasing, and lists return fields (id, title, church, price).

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 guides the agent to use this tool for browsing before purchasing with purchase_sermon, and mentions optional filters. However, it does not compare with search_sermons or other siblings, nor does it advise when not to use this tool.

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

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

With no annotations provided, the description carries full disclosure burden. It reveals that the tool is read-only (checking), requires authentication via consent_token, and only returns data for the user's own prayers. No mention of side effects or rate limits, but the core behaviors are covered.

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 consists of two efficient sentences. First states the purpose, second adds requirements and scope. No unnecessary words, front-loaded with core action.

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 tool with 2 parameters and no output schema, the description covers what it returns (count and answered status) and prerequisites. It could be improved by describing the output format or potential errors, but overall it is largely complete.

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 describes both parameters. The description adds no additional meaning beyond what the schema provides, thus 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 specifies the verb 'Check' and the resource 'prayer status' (how many people praying and if answered). It also defines scope: only for the user's own prayers, distinguishing it from submit_prayer_request.

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 the prerequisite of a previously submitted prayer request and the requirement of the same user's consent_token, implying when to use. However, it does not explicitly list alternative tools or when not to use it.

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

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

No annotations are provided, so the description carries the burden. It clearly states the tool uses public directory data only and returns no personal contact info. It enumerates output fields. It does not mention rate limits or authentication, but as a read operation with no side effects, the provided transparency is adequate.

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 primary action. Every sentence provides essential information: the first explains purpose and inputs, the second explains outputs. No redundant or extraneous text.

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 5 parameters and no output schema, the description covers inputs and outputs adequately. It lists return fields including the deep-linking community id. It does not describe error handling or empty result behavior, but for a straightforward search tool, this is nearly complete.

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 baseline 3. The description repeats parameter names ('latitude/longitude', 'optional radius, denomination filter') but adds no new semantic details beyond the schema. It does not clarify format constraints or default behaviors not 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 clearly states the verb 'Find' and resource 'churches near a location from SoapBox's public church directory'. It lists the specific outputs (name, denomination, city/state/country, website, distance, presence on SoapBox with community id). This sufficiently distinguishes it from sibling tools, none of which perform 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 indicates the tool is used when you have latitude and longitude coordinates, and optionally radius and denomination. It implicitly covers when to use, but does not explicitly state when not to use or provide alternatives. However, no sibling tool overlaps, so no exclusion is necessary.

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?

No annotations provided, so description carries full load. It implies read-only behavior via 'check' but lacks details on authentication, error cases, or side effects. Provides basic behavioral context.

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

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

Two sentences, front-loaded with main purpose, no redundant words. Example of efficient communication.

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 tool with no output schema, description fully explains what is returned and mentions related action (top-up). No gaps evident.

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?

No parameters exist, so baseline is 4. Description adds meaning by specifying the returned information (credits in cents, tier, daily rate limit), compensating for lack of output 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?

Clearly states 'check how many marketplace credits your API key has' with specific verb and resource, plus additional info about tier and rate limit. Distinct from sibling tools like purchase or top-up.

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?

Indicates when to use (checking balance) and when not (topping up), with explicit reference to topup API action. No direct comparison with other siblings, but context is sufficient.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states that the tool returns only the user's declared profile, not private prayers or journal, and emphasizes that explicit consent is required. It does not cover potential error states or rate limits, but for a simple read operation, this is adequate.

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 long, each serving a clear purpose: first states the tool's function and output, second provides usage instructions and a constraint. No unnecessary words, and the information is 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?

Given the simplicity of the tool (one parameter, no output schema, no annotations), the description covers all essential aspects: what is returned, required consent, what is not returned, and purpose. It is fully 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% with one parameter (consent_token). The description adds value by explaining that the token must have scope 'context:read' and be 'bound to this agent', which is not evident from the schema alone. It also emphasizes 'user's explicit consent', providing semantic clarity 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 explicitly states the action ('Read') and the resource ('portable faith context'), listing the specific fields returned (denomination, language, etc.). It is clear and distinct from sibling tools which are primarily about prayers, sermons, churches, etc.

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 indicates when to use the tool ('to tailor tone, tradition, and language') and explicitly states the prerequisite (consent_token with 'context:read' scope). However, it does not mention when not to use it or alternatives, though the context strongly implies it should be used only after obtaining consent and for personalization purposes.

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?

No annotations are provided, so the description carries full burden. It explicitly states daily readings are not included (licensed), no API key required, and implies read-only behavior. This is transparent about limitations and requirements.

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 key output and context. Every sentence adds value (purpose, usage, limitations). No wasted words.

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

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

Despite no output schema, the description adequately lists returned fields (season, color, year, feast). For a simple lookup tool with one optional parameter, this is complete information 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?

Schema coverage is 100% with one parameter. The description restates the schema's description ('optional date YYYY-MM-DD, defaults to today, UTC') without adding new meaning. Baseline 3 is appropriate.

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

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

The description clearly states it returns liturgical season, color, RCL year, and major feast for a given date, specifying tradition (Western RCL/Roman) and excluding daily readings. This is a specific verb-resource pairing that distinguishes it from other tools.

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

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

The description says 'Useful for date-aware, season-appropriate faith content' which gives context but does not explicitly state when to use this tool vs alternatives like get_faith_context or get_sermon. No exclusions or 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?

Discloses opt-in requirement, paid/free behavior, transcript withholding, and price return. No annotations, but description covers all key behaviors.

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 efficient sentences, front-loaded, no redundancy. Every sentence adds unique 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?

Covers all functional aspects for a fetch tool with two parameters, no output schema needed. Handles edge cases and prerequisites.

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?

Adds context beyond schema: sermon_id from search_sermons, include_transcript default true, and explains conditional transcript return based on payment.

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 it fetches full metadata and optionally transcript for one sermon by id, distinguishing from search_sermons and purchase_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?

Explicitly says when to use (after search_sermons), conditions (opted-in, paid/free), and prerequisite (purchase_sermon for paid 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?

With no annotations, the description carries full burden for behavioral disclosure. It indicates read-only lookup ('Look up') but does not describe what the response contains (e.g., full verse text, citation format), error handling, or any limitations like verse not 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?

One sentence, 12 words—extremely concise. No wasted words, but the lack of additional context means it may be too sparse for complex scenarios.

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 low schema coverage, no output schema, and many sibling tools, the description is too brief. It omits return value structure, error handling, and differentiation from similar tools like verify_scripture.

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 only 33% (book gets a description). The description merely restates the parameter names ('by book, chapter, and verse') without adding format, validation, or usage details beyond the schema's minimal info.

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 'look up' and resource 'KJV Bible verse by book, chapter, and verse.' It is specific about the scope (public-domain KJV) and parameters. However, it does not explicitly differentiate from sibling tools like get_lectionary or verify_scripture, but the distinct action is evident.

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?

No guidance is provided on when to use this tool versus alternatives, such as verify_scripture or get_lectionary. There are no exclusions or context cues, leaving the agent to infer usage from the name alone.

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 no annotations, the description carries full burden. It discloses passthrough nature, required consent and card, cap checks, idempotency. It doesn't detail failure modes or return values, but covers key behavioral aspects.

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?

Five sentences in a single paragraph, no wasted words. Front-loads action and constraints. Could be slightly more structured (e.g., bullet points), but efficiently conveys needed information.

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 no output schema, the description covers prerequisites, constraints, idempotency, currency. For a donation tool, it provides sufficient context for correct invocation without needing additional references.

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%, baseline is 3. Description adds value by explaining amount_cents in smallest unit, community_id source, consent_token scope, and idempotency_key purpose, going beyond schema descriptions.

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

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

The description clearly states the action (make a one-time donation), resource (church), and constraints (on behalf of user, within caps). It distinguishes from sibling tools like purchase_bundle or purchase_sermon which are for 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 provides when to use (making a donation) and prerequisites (consent_token, saved card). It notes when not to use (if amount exceeds caps) and suggests using idempotency_key, but doesn't explicitly contrast with alternatives like purchase_bundle.

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 no annotations, the description carries full burden. It reveals that the tool returns lexical data but does not mention read-only nature, idempotency, or any potential side effects. The simplicity of the tool makes this adequate but minimal.

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

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

Single sentence, front-loaded with the main action, and no extraneous words. It efficiently communicates the tool's 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?

Given the tool's simplicity (one parameter, no output schema), the description adequately covers input and output. It could be more complete by briefly noting the expected output format, but the listed return fields suffice.

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% (one parameter fully described). The description adds no further meaning to the parameter beyond what the schema provides (format example). Baseline 3 is appropriate.

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

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

The description clearly states the verb 'look up' and the resource 'Strong's Greek/Hebrew lexicon entry' along with specific return fields (lemma, transliteration, gloss, definition). This distinctively positions it against sibling tools like get_verse or verify_scripture.

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?

No guidance is provided on when to use this tool versus alternatives, such as get_verse for verse lookups or verify_scripture for cross-referencing. There are no exclusion criteria or context of use.

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 without annotations, the description fully discloses the behavioral traits: it's a purchase using prepaid credits, it's idempotent, it grants access to all sermons in the bundle, and it specifies the revenue split (70/30) and that it's a content sale, not a donation. No contradictions with annotations (none provided).

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

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

The description is three sentences long, starting with the primary action and purpose, then adding key behavioral notes. Every sentence adds value: purpose, details, and how to find bundles. No wasted words.

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

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

Given the tool has only one parameter, no output schema, and no annotations, the description covers the input sufficiently and explains the behavior. It could mention the expected output (e.g., confirmation or error), but the idempotency note implies a reliable outcome. Overall, it provides enough context for an agent to use 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 description adds meaningful context to the single parameter (bundle_id) beyond the schema, specifying it is the product_id from browse_catalog where type=bundle. Since schema coverage is already 100%, the description enhances understanding 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 explicitly states the action (buy a bundle), the resource (bundle/sermon series), and the payment method (prepaid marketplace credits). It distinguishes from the sibling purchase_sermon by noting the same revenue split and the bundle-specific behavior (grants access to every sermon in the bundle).

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 guidance on when to use this tool by directing to browse_catalog with type=bundle to find bundles. It mentions the same terms as purchase_sermon, giving context for comparison, but does not explicitly state when not to use it or list alternative tools beyond browse_catalog.

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 fee breakdown (70/30), that it's a sale not donation, idempotency, and that get_sermon returns transcript post-purchase. No annotations exist, so description carries this burden well.

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?

Description is a few sentences but each adds value. No wasted words, though slightly longer than necessary.

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 one required param, no output schema, and no annotations, description covers key behavioral context (fees, idempotency, post-purchase behavior) adequately.

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?

Only one parameter with full schema coverage. Description merely restates schema's 'from search_sermons results' and adds context about credits, not additional semantic detail.

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 it buys permanent access to a paid sermon using credits. Distinguishes from get_sermon and donations, and implies difference from purchase_bundle.

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?

Explains when to use (to purchase sermon) and what to do if insufficient credits (check balance and top up). Mentions idempotency. Could explicitly contrast with purchase_bundle.

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?

No annotations provided, so description carries full burden. It states the tool is impartial and returns a rating, score, summary, and loci. However, it does not disclose potential limitations, data sources, rate limits, or authentication requirements beyond 'No key required'.

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

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

Two concise sentences: first defines the core purpose, second adds key attributes (impartiality, return values, non-proselytizing, no key). Front-loaded and no redundant information.

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 two simple parameters and no output schema, the description adequately covers the tool's purpose, inputs, and return values. It could be more complete by explaining how the assessment is derived, but it provides sufficient context for an AI agent to decide whether to use 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 description coverage is 100%, so baseline is 3. The description adds value by listing example traditions and clarifying the statement max length indirectly (schema explicitly says 1500 chars). It also explains what the tradition parameter entails, which is helpful 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 specifies the verb 'assess', the resource 'alignment with a named Christian tradition's historic doctrinal positions', and provides concrete examples of traditions. It clearly distinguishes from siblings like get_faith_context and verify_scripture by focusing on doctrinal alignment.

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 mentions 'No key required' and 'Analytical, not proselytizing', but does not explicitly state when to use this tool versus alternatives (e.g., get_faith_context for general context, verify_scripture for scripture verification). Usage context is implied but lacks clear exclusion criteria.

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 no annotations provided, the description explains key behaviors: semantic search, consented sermons only, ranked results, and specific fields returned. It does not cover rate limits or authentication, but for a search tool, the transparency is adequate.

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

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

The description is three sentences long, front-loading the core action and condition, with no wasted words. It is structured logically: what it does, what it returns, and a usage recommendation.

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 search tool with 3 parameters and no output schema, the description covers all essential information: search scope (consented sermons), result format, and usage purpose. It is fully adequate for an AI 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?

100% schema coverage means the schema already documents parameters (query, church_id, match_count). The description adds no new semantic detail beyond what is in the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly defines the tool's purpose: semantically search real sermons on SoapBox with pastor consent. It specifies the return data (excerpts, title, church, speaker, scripture, start-time) and differentiates from siblings like get_sermon by focusing on content 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 advises using the tool 'to find what churches are actually preaching on a topic' and notes the consent condition. While it gives clear context, it does not explicitly state when to avoid this tool or list alternatives among the 18 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?

No annotations provided, so description carries full burden. It discloses the need for user consent, the requirement of scope, and the return value. Mentions follow-up tool for status. Slight lack of detail on privacy effect but otherwise transparent.

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

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

Two sentences, no redundant words. Front-loaded with purpose and key constraint (on behalf of a user). Efficient and to the point.

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?

Tool has 3 well-documented params, no output schema, and no nested objects. Description covers behavioral context, prerequisites, return value, and follow-up. Adequate for agent use.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add meaning beyond schema for 'content' or 'is_private'; consent_token's scope is already in schema. No extra parameter insights.

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

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

Description clearly specifies the verb 'Post', the resource 'prayer request to SoapBox's prayer wall', and the purpose 'so their community can pray for it'. It distinguishes from sibling 'check_prayer_status' by describing its own action.

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

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

Explicitly states when to use (to post on behalf of a user), prerequisites (consent_token with scope), and what is insufficient (API key alone). Also suggests checking status via 'check_prayer_status'.

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?

No annotations are provided, so the description bears full burden. It discloses caching behavior and cost requirement (API key), but omits rate limits, error handling, or whether returned URLs expire. Adequate but not thorough.

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 front-load the main action and key constraints (cached, cost). 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?

Given no output schema, the description explains the result (playable audio URL) and mentions caching and cost. It does not address potential URL expiration or rate limits, but covers the essential context for a simple TTS tool.

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

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

Schema coverage is 100%, meeting the baseline. The description adds no param-specific meaning beyond what the schema already provides (e.g., language BCP-47, voice/gender). Caching and cost are global, not per-parameter.

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 generates spoken audio from text in 50+ languages and returns a playable URL. It specifies content types (verse, prayer, devotional) and distinguishes from siblings by being the only text-to-speech tool.

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 does not explicitly state when to use this tool versus alternatives. It mentions caching and cost (API key required), which implies usage caution but lacks explicit when-not or alternative suggestions.

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?

No annotations provided, so description carries full burden. It discloses the return details: match, KJV reference+text, confidence score, attribution correctness. It implies read-only operation but does not mention error handling or limitations.

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 purpose, and every sentence adds value. No redundancy or filler.

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

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

Despite no output schema, the description lists all key return elements. It covers the main use case but could mention what happens if the quote is not found or invalid input.

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 simple descriptions. The description adds context: explains the optional reference triggers attribution checking and specifies KJV version. This goes beyond the schema.

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

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

The description clearly states 'Verify whether a quote is real Scripture and cited correctly' with the specific verb-resource combination. It distinguishes from siblings like get_verse by emphasizing anti-hallucination and attribution checking.

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

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

The description explicitly says 'Use this before presenting any Bible quote to avoid misquotes/fabrications' and explains behavior with/without a claimed reference. It does not explicitly state when not to use, but context is clear.

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