msza.ai — Polish Catholic Sermons ✝

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

Annotations already cover read-only/idempotent/non-destructive, but the description adds substantial extra context: results ordered by lexicographic session_id not chronology, a 200-candidate scan ceiling, no content generation/Bible-text retrieval/network access, and per-page consumption of the shared listing quota. These are behavioral traits that go well beyond the annotation set.

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 core matching behavior is front-loaded, and most of the seven sentences carry distinct information (ordering, scan cap, quota, exclusions). It is dense but nearly every clause earns its place; only the 'No content generation, Bible-text retrieval, or network access' sentence feels slightly defensive.

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

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

With an output schema present, return values need not be described. Given the tool's complexity, the description covers the critical operational facts an agent needs: matching semantics, ordering, pagination quota cost, and scan limits. 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?

Schema coverage is 100%, so the baseline is 3, but the description still contributes meaning: the single-chapter verse-range constraint and, most notably, that each page consumes the shared listing quota and is capped at 200 chapter candidates. The scope semantics are largely mirrored from the schema, keeping this from a 5.

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 precise verb+resource ('Returns public saved recordings whose saved Bible annotations exactly overlap the requested single-chapter verse range') and immediately pins down the exact matching semantics. It is easily distinguished from siblings like get_bible_passage, get_sermon, and search_msza_ai.

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 clarifies scope selection (sermon vs session) and explicitly positions the tool against alternatives by stating matches are stored annotations rather than semantic search or verified evidence, which implicitly routes semantic queries elsewhere. It stops short of naming the sibling to use instead, so it earns a strong 4 rather than 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 readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower; the description still adds real value by disclosing immutability semantics, the head-vs-snapshot resolution rule, and that the payload contains complete skillMarkdown plus metadata.

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 tight sentences, front-loaded with the verb and key, then version semantics, then return shape, then the boundary against publishing. No filler and nothing buried.

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 tool with a full output schema, annotations covering safety, and a closed-world hint, the description supplies everything needed to invoke correctly: key format, version semantics, and the scope boundary.

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% and both property descriptions already spell out kebab-case slug format and the head-vs-version behavior, so the description largely restates structured data. It adds contextual framing but no syntax or constraint the schema lacks, so baseline 3 is right.

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?

States a specific verb (returns) plus resource (one immutable public Agent Skill) and pins the lookup key (exact lowercase slug, optional x.y.z version). The singular 'one' and the mention of a separate publishing endpoint distinguish it from list_agent_skills and any write counterpart.

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 the two retrieval modes clearly: omit version for the current published head, supply version for that immutable snapshot. It also steers publishing away to a separate authenticated endpoint, giving one explicit exclusion, though it never names list_agent_skills as the discovery 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?

Annotations already cover readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: an exceptional safety limit fails loudly instead of returning partial text, source_sermons draws from at most 200 linked candidates, sources_truncated refers to the candidate cap and not text truncation, and the response flags AI-generated origin with provenance fields. That is material context an agent could not get from the structured fields.

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

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

Purpose is front-loaded in the first sentence and each subsequent sentence carries a distinct disambiguation (fail-explicit behavior, candidate cap vs. truncation, provenance). It is dense and slightly prose-heavy, but no sentence is 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?

An output schema exists, yet the description still clarifies the two most confusable return fields (source_sermons and sources_truncated) and the provenance marker, so an agent knows what a successful response means. Nothing needed to invoke the tool 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?

There is a single parameter and schema description coverage is 100%, with the schema already explaining that study_id is an exact sourceId from search_msza_ai or a canonical msza.ai URL. The description's 'by study_id' adds no format or syntactic detail beyond that, so the 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?

The description gives a specific verb+resource with scope: 'Returns one saved public AI study by study_id with its complete public text and source-sermon metadata.' This clearly separates it from list/search tools and from get_sermon by naming the AI-study resource. It stops short of naming a specific sibling to route away from, so it lands just below the top tier.

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 body offers no when-to-use or when-not-to-use guidance and never names an alternative such as search_msza_ai or get_sermon. The only hint that this is a follow-up to a search lives in the schema's study_id description, not in the tool description itself.

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 establish readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered — but the description goes well beyond that. It discloses that sermon and full-recording fallbacks are excluded, that text_type signals AI-edited or summarized rather than verbatim speech, that recording/summary-update dates are not expiry dates, the 8000 UTF-16 truncation limit with truncated/total_chars completeness flags, that no AI generation or network retrieval occurs, and that shared rate limits apply. This is unusually rich 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 core purpose and section preference are front-loaded in the first sentence, and the remaining sentences are dense caveats rather than filler — each carries a distinct constraint (fallback exclusion, text_type meaning, date semantics, truncation, no AI, rate limits). It is information-heavy but not padded, though the caveat sentence about truncation is close to restating what the output schema already exposes.

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

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

With an output schema present, return-value structure need not be explained, and the description nonetheless covers the two things an agent could get wrong: the 8000-unit truncation and the semantics of text_type and the session dates. Combined with the session-state precondition and the rate-limit note, nothing needed to call this tool 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% and the schema description already defines session_id as an exact public recording session ID with length bounds and a source example, so the baseline is 3. The description adds qualifying semantics the schema does not: the session must have ended or been interrupted, and it must contain saved announcements for a result to exist.

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 gives a specific verb and resource ('Returns saved parish announcements') and immediately narrows the scope to 'an ended or interrupted public session', naming the exact section preference (edited announcements section, else summary tab). That precision distinguishes it from siblings like get_sermon and get_transcript without the agent needing to open their schemas.

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?

Usage context is implied by the 'ended or interrupted public session' qualifier, which tells the agent this is for completed recordings rather than live or in-progress ones. However, no sibling is named as an alternative and there is no explicit when-not-to-use statement, so the agent must infer the routing from the content caveats 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?

Annotations already declare readOnly, idempotent, closed-world, non-destructive behavior, so the safety profile is covered; the description adds real context beyond that: a 50-verse cap, that copyright/license/source attribution is returned, and that output is unmodified source text. It does not discuss error behavior for out-of-range chapters or verses, so not a 5.

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, each earning its place: capability and cap first, identifier format second, the negative guarantee last. No filler and the scoping constraint 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?

An output schema exists, so return values need not be explained, and the description still adds the attribution content and the 50-verse ceiling. Coverage is strong for a read tool, with only minor gaps such as no guidance on the sibling search tool for locating passages by reference.

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 book_id, chapter, start_verse, and end_verse all documented including bounds and the inclusive-omit convention, so the baseline is 3. The description's mention of USFM IDs (GEN, PSA, MAT, JHN) largely restates the schema's own book_id description and adds only marginal new meaning.

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

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

States a specific verb and resource ('Returns up to 50 unchanged UBG verses from one chapter'), names the scope, and explicitly disclaims translation or AI generation, which distinguishes it from AI-search siblings like search_msza_ai. An agent can identify the operation without opening the schema.

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?

Usage is implied by 'unchanged UBG verses' and 'No translation or AI generation occurs', which hints this is the verbatim-text tool rather than a search tool, but there is no explicit when-to-use statement and no named alternative (e.g., find_sessions_by_bible_passage or search_msza_ai).

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety bar is low. The description adds genuinely useful context beyond them: profiles may be AI-enriched, Mass schedules may be outdated, and the result is a stored snapshot with no refresh or generation triggered.

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 tight sentences: identity first, staleness caveat second, non-mutating behavior third. No filler, and the most decision-relevant facts 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?

For a single-parameter read with full annotations and an output schema, the description covers what the agent needs: the lookup key, the staleness risk, and the fact that no generation is triggered. Enumerating return fields is slightly redundant against the output schema, but nothing important 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% and the single camera_id parameter is already documented as an exact public camera_id returned by list_churches. The description's "by camera_id" adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ("Returns a saved public church profile by camera_id") and enumerates the returned fields, so an agent knows exactly what this fetches. It does not explicitly distinguish itself from the sibling list_churches (that routing only appears in the schema's camera_id description), so it falls short of full sibling differentiation.

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 result reads saved data without profile refresh or generation" implies this is the cheap lookup path, but the description never states when to use this tool versus list_churches or what prerequisites exist. Usage is only inferable, not stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the bar is lower. The description still adds real value: it discloses that data is served from stored SQLite content with no generation or refresh, and it explains the semantics of the sermon_aggregates_available flag, including that false makes digest counters placeholders.

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 most important information (what it returns, then the date behavior) is front-loaded, and each sentence carries content rather than filler. The sentence about synthesis/digest provenance is somewhat jargon-heavy, but it is not wasted given the flag's importance.

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?

An output schema exists, so return structure need not be restated, yet the description still flags the one field an agent must interpret (sermon_aggregates_available) and cautions that AI-generated thoughts are orientation material. Combined with the source-of-data note, this is nearly complete for a single-optional-parameter 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% and there is only one parameter, so the baseline is 3. The description reinforces the default-to-today behavior and names the Europe/Warsaw timezone, but the schema already specifies 'Warsaw calendar date' and the YYYY-MM-DD pattern, so the added meaning is marginal.

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 ('Returns an already-prepared public /dzisiaj briefing') and enumerates its contents (daily thought, readings, patrons, name days, homilies, sermon links). This clearly distinguishes it from siblings like get_sermon, get_ai_study, or search_msza_ai without needing their schemas.

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

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

It explains the date parameter usage ('omit it to use today') and what the payload contains, which implies the use case. However, it never states when to prefer this over sibling tools such as get_sermon or search_msza_ai, nor any exclusions or prerequisites, leaving selection to 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 already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the marginal bar is lower. The description still adds real traits: results are bounded, carry canonical source URLs, are capped at 20 indexed Scripture references, and session-derived profiles are gated behind provenance verification — none of which is in the annotations or schema.

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 the core action and followed by a scoping caveat and a result-shape preview. Every sentence carries information, though the provenance sentence is dense and slightly jargon-heavy for what is a simple single-parameter lookup.

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?

An output schema exists, so return values need not be explained, yet the description usefully previews their boundedness and the 20-reference cap. For a one-parameter, non-destructive read tool with full annotation coverage, nothing an agent needs to invoke 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?

There is a single parameter with 100% schema description coverage, and the schema already explains the ID's origin (search_msza_ai sourceId or get_sermon.references ids). The description only restates the 'exact public person ID' constraint, adding the 'exact' qualifier but no new format or derivation 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?

States a specific verb and resource ('Returns one curated Catholic or biblical person profile') and bounds it by an exact public person ID. The scope qualifier 'curated ... public' distinguishes it from the session-derived profile variant that the next sentence declares unavailable, so an agent can tell what entity this tool resolves without ambiguity.

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?

Gives a concrete usage precondition ('by exact public person ID') and an implicit exclusion: session-derived dynamic profiles are unavailable. It does not name a sibling tool as an alternative route to person data, so it stops short of full when/when-not/alternatives routing.

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, idempotentHint, non-destructive and closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral detail: results are 'bounded profile fields' with 'canonical source URLs' capped at 'at most 20 indexed Scripture references', which tells the agent about result sizing 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 tight sentences with zero waste; the purpose and scope lead, and the return-content constraints follow immediately.

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 a full output schema present, the description needn't explain return values, and it appropriately summarizes what the profile contains and how it is bounded. Safety traits are covered by annotations and the sole parameter is fully documented, leaving nothing critical missing for a single-ID 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 coverage is 100% and the single parameter is fully documented in the schema itself (exact sourceId, min/max length). The description only restates that the ID must be 'exact', adding no syntax or provenance detail beyond the schema's own note.

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?

States a specific verb and resource ('Returns one public Catholic or biblical place profile') and scopes it by exact public place ID. It clearly distinguishes the 'place' resource from sibling resources like get_church, get_person and get_sermon, though it never names a sibling to route against.

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 phrase 'exact public place ID' implies the ID must already be known, and the schema notes it comes from search_msza_ai or get_sermon.references, but the description itself gives no explicit when-to-use, prerequisites, or alternatives for looking up a place.

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

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

Annotations already declare read-only, idempotent, closed-world behavior, yet the description adds real value beyond them: content may be partial (a song may expose only a first line or metadata), rights_note is provenance rather than a permission grant, and text is stored rather than generated or fetched. These are behavioral caveats an agent would otherwise get wrong.

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 tight sentences, front-loaded with what is returned before the ID and content-status caveats. The final sentence about stored versus generated text is near-redundant with openWorldHint=false but still clarifies the distinction, so it earns its place only marginally.

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

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

With an output schema present and rich annotations, the description need not explain return values; it focuses on the non-obvious parts (partial content, rights semantics, ID namespacing). It could still state when an ID is unavailable or what happens on a missing item, which is the one remaining gap.

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

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

Schema description coverage is 100% and the single parameter already documents the bare and namespaced (song:<id>, standard:<id>) ID forms. The description restates the same ID forms without adding syntax, precedence, or error-handling detail, so it sits at the high-coverage 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?

States a concrete verb and resource and, unusually, enumerates the three content types the resource can hold (prayer, song, fixed liturgical text), which prevents an agent from assuming this is prayer-only. It does not explicitly contrast itself with any sibling tool, but the resource is distinct enough that confusion is unlikely.

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?

Usage is only implied: the agent can infer it needs an ID obtained from search or a transcript/sermon reference, but the description never says when to call this versus get_sermon, get_transcript, or search tools, and gives no exclusions or preconditions.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), freeing the description to add genuinely new context: text_type may be AI-edited or fallback rather than verbatim, truncated/total_chars signal completeness, references caps at 50 saved annotations, and those annotations may be machine-generated and incomplete. These data-fidelity caveats are real behavioral disclosure 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?

Front-loaded with the purpose sentence, then a compact series of caveats. It is not bloated, though the back half reads as a run-on chain of field explanations (text_type, truncated/total_chars, references, selected_section, session) without clear separation, which slightly hurts scanability.

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 annotations carrying safety and an output schema present, the description need not restate return structure, yet it still supplies the interpretive nuance (verbatim caveat, annotation reliability, reference cap) an agent needs to use results correctly. Only routing guidance relative to its siblings is absent.

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% and there is a single parameter, so the schema already documents session_id fully, including its max length and source tools. The description adds nothing about the parameter beyond the schema, so the baseline 3 for high coverage is correct.

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

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

States a specific verb and resource: "Returns public sermon text for an exact session ID in its stored language." An agent can tell this is a lookup-by-ID read tool. However, it never distinguishes itself from the sibling get_transcript, which occupies very similar territory, so differentiation is missing.

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?

There is no when-to-use / when-not-to-use guidance and no mention of the alternatives. Given siblings like get_transcript, list_recent_sermons, and list_sermons_by_date, an agent has to guess which retrieval path applies. Only the implicit 'you already have a session ID' scenario hints at 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?

Annotations cover readOnly/idempotent/non-destructive, yet the description adds substantially more: page caps of 20 segments and 12000 UTF-16 units, cursor and char_offset continuation semantics, privacy redaction, retained timestamp metadata, stable ordering, live-pagination cursor invalidation, and explicit failure on oversized segments. These are behavioral traits the annotations cannot express.

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 most important differentiator (final transcript vs AI-edited sermon) is front-loaded, and every sentence carries distinct information. However, it is delivered as one dense multi-clause block, which is heavier than necessary for readability.

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?

An output schema exists so return values need no explanation, and the description still thoroughly covers pagination mechanics, limits, ordering, redaction, and failure modes. For a two-parameter paged read tool, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining how next_cursor invalidates under live edits and how long segments continue via char_offset. That adds real operational meaning for the cursor 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 opens with a specific verb+resource ('Returns saved final transcript segments') and immediately scopes it ('from an ended or interrupted public session') while naming what it is not ('rather than an AI-edited sermon section'), which cleanly separates it from get_sermon. An agent can select this tool without opening the schema.

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 contrast with an AI-edited sermon section gives clear implied routing, and the schema-backed precondition (ended/interrupted public sessions only) frames when the tool applies. It stops short of an explicit 'use X instead when' clause naming get_sermon directly, so it lands just below the top band.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: skills are immutable, results are summaries lacking full Markdown, and publishing lives on a separate authenticated endpoint. It stops short of 5 because the pagination bounds are left entirely to the schema.

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 dense sentences, front-loaded with the core return contract before the filter and the read-only caveat. No filler, no repetition of the title.

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

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

With an output schema present, the description need not explain return values, and it nevertheless characterizes them. Combined with full schema coverage and rich annotations, an agent has everything needed to call this correctly. A small gap remains around default page size ('up to 50' vs. the limit default of 20).

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 filtering is by 'one exact tag' (single value, exact match) and caps returns at 'up to 50', but adds no syntax or semantics beyond what the tag/limit/offset descriptions already state.

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?

States a specific verb and resource with scope: 'Returns ... public Agent Skill summaries from the msza.ai catalogue'. The phrase 'metadata and canonical links without full Markdown' implicitly differentiates it from the single-skill fetch, though it never names the sibling get_agent_skill, so it stops short of a 5.

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?

Gives a clear when-not: 'The catalogue is read-only; publishing belongs to a separate authenticated Hermes endpoint', which steers the agent away from expecting write behavior here. It also frames the tag filter as an optional refinement ('optionally filtered by one exact tag'). It does not explicitly route to get_agent_skill for full detail, so it lacks the explicit alternatives that would earn 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 readOnly/idempotent/non-destructive, so the description's added value is real: it discloses the 50-per-page cap, stable ordering, the `truncated` signal, and that the catalogue can change mid-traversal — an important caveat for cursor consumers. It stops short of describing what happens if the cursor expires or how the filter interacts with result drift.

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 short sentences, front-loaded with the core behavior, then pagination mechanics, then the staleness caveat. No filler, though the phrasing is terse enough that the 'truncated' and 'camera ID' references rely on the reader already knowing the domain.

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?

An output schema exists, so return values need no explanation, and the description plus annotations plus full schema coverage give an agent everything needed to page correctly through a filtered, live-changing result set. Minor gap: no guidance on cursor invalidation or re-filtering behavior.

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 limit, query and cursor in detail. The description's restatement ('same optional literal name/address substring filter', cursor tied to the same query) reinforces the workflow but adds nothing the schema does not already say; 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?

The first sentence names a specific verb and resource plus scope ('enabled public churches') and ordering, so an agent knows exactly what comes back. It does not explicitly route away from the singular sibling get_church, leaving that differentiation to inference from the name.

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?

Pagination usage is well implied ('next_cursor represents the next page', 'null marks the end'), which tells an agent how to traverse. But there is no explicit when-to-use-this vs alternatives guidance, e.g. when to prefer get_church for a single record or how this differs from the other list_* 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavioral facts the annotations do not: the 10-item cap, that it is non-paginated, the sort order, and that results are compact metadata plus excerpts rather than full content.

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

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

Two sentences, front-loaded with the resource and the bound, then the optional filter. No filler, no repetition of the title.

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?

A one-optional-parameter read tool with an output schema and rich annotations needs little more; the description supplies the cap, ordering, non-pagination, and payload shape. Everything required to call it correctly is present.

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 single parameter is already fully documented in the schema, including the 'omit to list from all churches' behavior. The description's 'optionally limited to one church' merely restates that, and notably avoids explaining the church/camera_id naming, adding no new syntax or semantics. 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?

States a specific verb (returns/lists) and resource (public msza.ai sermons) plus the exact scope: up to 10, reverse chronological, optionally one church. This cleanly separates it from get_sermon (single) and list_sermons_by_date (date-driven), so an agent can pick it without opening the schema.

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 word 'latest' plus 'reverse chronological' implies when this tool fits, and 'optionally limited to one church' hints at the filtering choice. But no sibling is named as an alternative and there is no explicit when-not guidance, so usage is only implied.

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 the safe read-only, idempotent, non-open-world profile, so the description clears the lower bar by adding real behavioral context: a hard 50-record non-paginated ceiling and the total/truncated fields that signal truncation. It does not explain what happens when the ceiling is hit beyond naming those fields.

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

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

Two tight sentences, front-loaded with the core behavior and the optional narrowing in second position. The closing clause about total/truncated is slightly awkwardly phrased ('describe the safety ceiling') but earns its place by flagging truncation risk.

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?

An output schema exists, so return values need not be detailed; the description still flags the record cap and truncation fields, which is the key operating constraint. Given the simple two-parameter read tool, little is missing, though the truncation/next-step behavior is only hinted at.

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 both parameters (date format/zone, camera_id as optional church filter) are fully documented upstream. The description's 'optionally limited to one church' and day-scoping restate the schema rather than adding syntax or edge-case meaning, so the 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?

States a specific verb and resource ('Returns public sermons') plus the exact filter scope (start time on one Europe/Warsaw calendar day, optionally one church). This clearly separates it from siblings like list_recent_sermons and get_sermon without needing the schema.

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?

Usage context is implied by the date-scoped framing and the note that camera_id can be omitted to widen to all churches, but no alternative tool is named and no when-not guidance is given (e.g. use list_recent_sermons for a rolling window). Adequate but inferential.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses real behavioral traits: results retain stored source language, return candidate matches with stable IDs, citation labels, excerpts, dates and links, filters are scoped only to sermon records, and priest names are unavailable. These are non-obvious constraints an agent could not infer from 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?

Three sentences, each earning its place: scope first, then result shape, then filter/limitation caveats. No filler and the most important framing (what is searched) 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?

With an output schema present and 100% parameter coverage, the description covers the remaining gaps an agent needs: which sources are searched, that results are candidate matches with citations, that date/church filters only touch sermons, and that priest names are unavailable. Nothing required 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 description coverage is 100%, so the schema already documents all eight parameters, including content_types semantics and date filter scoping. The description echoes the sermon-only filter constraint and the priest-name limitation but adds little syntax or format detail beyond what the schema provides, so 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?

The description gives a specific verb and resource set: searching public msza.ai sermons, studies, Bible passages, prayers, songs, people and places by topic, keyword and relevance. That distinguishes it from the get_*/list_* siblings, which are ID- or listing-oriented, though no sibling is named explicitly.

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?

Usage is implied by 'by topic, keyword, and relevance' (discovery-style lookup) and by the note that date/church filters apply to sermons. However, there is no explicit when-to-use guidance versus get_sermon, get_person, or list_sermons_by_date, and no statement of when this tool is the wrong choice.

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