Good Turn Studio (all tools)

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds real value: it discloses the return format (plain text letter with [brackets] placeholders, an attachment checklist, tips) and the key operational boundary that it 'never sends or files anything.' These are behaviors not visible in 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?

Front-loaded with purpose, then triggering examples, then output/behavior. Four sentences, each carrying information, with no boilerplate. Slightly dense in the middle but nothing is wasted.

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 14-parameter, all-optional drafting tool with no output schema, the description covers what the tool produces and that it does not send anything. It does not explain how placeholder substitution or checklist generation works, but nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% across 14 properties, so the schema already documents every parameter, including enums and the reason/denial_code fallback. The description adds only the implicit note that unfilled fields become [brackets] placeholders, which is marginal beyond what the schema states. 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 artifact ('Draft an appeal letter') and adds scope in the title ('for the user to review and send'). This clearly separates it from siblings like get_appeal_deadlines or explain_denial_code, which inform rather than produce a document.

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 two concrete triggering utterances ('my insurer denied my MRI as not medically necessary' and 'write an appeal letter for an out-of-network denial'), which tells the agent when to pick this tool. It does not explicitly name alternative siblings or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral detail beyond that: it explains the return content (plain-language meaning, who fixes it, billability derived from the CO/PR/OA/PI group code, and a conditional letter link), which is not inferable from annotations.

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

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

The purpose and example triggers are front-loaded and every sentence carries information. Minor waste in restating the product/title ('Appeal My Claim. Explain the denial codes...') before the operational content, but the description remains tight and single-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?

There is no output schema, so the description correctly takes on the burden of describing return values, and it does so thoroughly. For a two-parameter read-only lookup with full schema coverage, an agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by naming real code formats (CO-50, PR 204, 197, N130) and explaining that the group-code prefix (CO, PR, OA, PI) drives the billability determination. That enriches interpretation of the required 'code' 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 states a specific verb and resource ('Explain the denial codes on an Explanation of Benefits') and is immediately distinguishable from siblings like appealmyclaim_draft_appeal_letter and appealmyclaim_get_appeal_rights. An agent can tell exactly what this tool returns without opening a 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?

Concrete trigger phrasings ('my EOB says CO-50, what does that mean?', 'what is denial code PR 204?', 'what does N130 mean?') give clear when-to-use context. However, it never names an alternative tool or an explicit when-not-to-use condition, so routing versus formguide/lore-style siblings is left 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 establish readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds genuinely new behavioral context: the output is an approximate file-by date rather than an authoritative deadline, and the user should verify against their own notice - an important caveat not captured anywhere else.

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 and then the example phrasings, with zero filler. The opening 'Appeal My Claim. How long someone has to appeal...' partially duplicates the title, a minor redundancy.

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

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

No output schema exists, so the description carries the return-value burden; it does this by describing the approximate file-by date and the verification caveat. Combined with full schema coverage and complete annotations, an agent has what it needs, though the output format itself remains somewhat unspecified.

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

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

Schema description coverage is 100%, with each parameter documented in the schema itself (including the enum on urgent). The description only alludes to denial_date ("with the date on the denial notice") and adds nothing about urgent or plan_type, so baseline 3 is appropriate.

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

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

The description states a specific informational purpose - how long someone has to appeal and how fast the plan must decide - with concrete example user phrasings. It is distinguishable from siblings like get_appeal_rights and draft_appeal_letter, though it never states an explicit verb for what the tool returns.

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 gives clear triggering questions ("how long do I have to appeal?", "when is my appeal due?") and the condition for usefulness (have the denial date handy). It does not explicitly name sibling alternatives such as get_appeal_rights for the 'when/not-this-tool' case, so it stops short of a 5.

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

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

Annotations already establish the safe read-only, idempotent, closed-world profile, so the bar is lower; the description adds real value by enumerating what is returned (who decides, the appeal steps, deadlines, and where to get free help). The fallback behavior when plan_type is omitted is also disclosed, though no rate limits or data-freshness notes are given.

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-loads the purpose and packs example phrasings into a single compact block, and each sentence serves a routing or fallback function. The opening 'Appeal My Claim. Appeal rights, steps and free help for a plan type and state' restates the title verbatim, a minor redundancy.

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

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

With no output schema, the description carries the return-shape burden and does so by listing the categories of information returned. Combined with the handling of the optional plan_type and state inputs, it is essentially complete for calling the tool correctly, missing only any note on coverage limits or data recency.

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 both parameters are already documented, including the state format and the plan_type default. The description reinforces the default ('leave it out to get the rules for most private plans'), which slightly clarifies behavior but largely restates the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource (get appeal rights, steps and free help) scoped by plan type and state, and the example queries make the intent unambiguous. It does not explicitly name or differentiate from its siblings (get_appeal_deadlines, draft_appeal_letter), so sibling routing is left implicit.

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?

Provides concrete trigger phrasings ('what are my appeal rights in California?', 'my insurer denied my claim, what can I do?') and a fallback for the unknown-plan-type case, which is strong usage context. However, it does not say when to prefer this over appealmyclaim_get_appeal_deadlines or appealmyclaim_draft_appeal_letter, despite overlapping on the deadlines content.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one useful behavioral trait - output is chunked one line at a time and shaped for voice - but says nothing about ordering, how many cards exist, or whether reads are cached.

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?

It is short, but the opening repeats the title verbatim and the closing clause ('Bible: daily readings, plans, search and passage lookup (World English Bible)') is app-level scope that does not help select this specific tool. The redundant period and brand restatement are wasted tokens.

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?

Not applicable at the highest bar - scored 3: with annotations covering safety, a fully documented schema and no output schema, the definition is serviceable, but it leaves the central concept ('card', 'one line at a time') undefined and does not clarify its relationship to the sibling reading/today tools.

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 n, date and reading all documented in-schema (including defaults for card index, UTC day, and reading id from /readings). The description adds no parameter meaning beyond that, 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 conveys that this returns today's reading 'one line at a time' as a swipeable card, which is more specific than a bare restatement of the name. However, it never explains what a 'card' is relative to the near-identical siblings bible_get_today, bible_get_reading and bible_get_passage, so an agent cannot easily tell which to pick.

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 only usage signal is the trailing phrase 'for voice', which hints at a text-to-speech context but is not framed as a when-to-use rule. There is no guidance on choosing this over bible_get_today or bible_get_reading, and no exclusions are 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds that the translation is the World English Bible, which is genuine context, but says nothing about return shape, verse numbering, or reference parsing behavior.

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 short sentences with the resource and scope front-loaded and no filler. The marketing-style opener 'Bible Swipe' consumes space without adding information, but the remainder is efficient.

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

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

For a single-parameter, read-only lookup with full annotation coverage and no output schema, the description supplies the translation and valid reference formats. It still leaves open book-naming conventions (full name vs abbreviation) and what a returned passage looks like, so it is adequate but not 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% and there is only one parameter, so the baseline is 3. The description goes beyond the schema's single 'John 3:16' example by enumerating the accepted reference forms (single verse, range, whole chapter, cross-chapter range such as Genesis 1:1-2:3), which materially expands what the agent knows it can pass.

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 identifies the resource precisely (a Bible passage, any verse/range/chapter, World English Bible translation) and the scope of accepted references. The verb is only implied by the tool name, and nothing distinguishes it from siblings like bible_get_reading, bible_get_card, or bible_get_today.

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: you call it when you want a specific passage by reference, and the listed reference shapes (verse, range, chapter, cross-chapter) tell the agent what it accepts. However, there is no explicit when-to-use guidance and no mention of the sibling read tools an agent might otherwise pick.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered elsewhere. The phrase 'line by line' is the only behavioral hint (a possible line-by-line return format), and no auth, rate-limit, or error context is added. The description contributes almost nothing 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?

It is short, but the first two fragments ('Bible Swipe' and 'One reading or plan, line by line') duplicate the title, and the third sentence describes the broader app rather than this tool. Sentences do not earn their place, so brevity here reflects thinness rather than discipline.

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 single-parameter read tool with full schema coverage and complete safety annotations, the description's remaining job is disambiguation, which it fails. An agent still cannot tell this apart from bible_get_passage or bible_get_today.

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 schema itself explains the id thoroughly (reading/plan id from /readings, or a plan name like 'japji'). The description adds no parameter detail, so the baseline of 3 is appropriate.

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

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

The description mostly restates the title and adds a brand tagline ('Bible Swipe'). 'One reading or plan, line by line' only loosely hints at retrieving a single reading/plan, and it never distinguishes this tool from close siblings like bible_get_passage, bible_get_today, or bible_list_readings. An agent cannot confidently separate it from those without opening 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?

There is no when-to-use guidance, no prerequisites, and no named alternative. The trailing sentence 'Bible: daily readings, plans, search and passage lookup' describes the whole product surface rather than telling the agent when this specific tool applies.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false. The description adds no further behavioral context—no authentication needs, rate limits, error conditions, or detail about the return format beyond the title's 'line by line' phrase.

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 short but not front-loaded with useful information. The first sentence 'Bible Swipe.' is redundant, the second repeats the title, and the third is generic filler about Bible features that do not apply to this specific tool.

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

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

For a simple read-only tool with full schema coverage and annotations covering safety, the description minimally conveys that it returns today's reading line by line. However, it fails to clarify how this differs from sibling 'get_reading' tools or what a 'reading' actually contains, leaving a small but real ambiguity.

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 single optional 'date' parameter has full schema description coverage ('Optional day as YYYY-MM-DD. Defaults to today (UTC).'), so the schema carries the semantics. The description does not mention the parameter at all, which is acceptable given the high coverage but adds no value.

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 begins by restating the title verbatim ('Today's reading, line by line (same as the app shows today)') and adds only a generic service blurb about Bible content. It does not distinguish this tool from bible_get_reading, bible_get_card, or bible_list_readings, leaving the agent to guess which one returns the daily reading versus a specific passage.

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 when-to-use guidance is given, and no alternative tools are mentioned. The agent gets no signal for choosing between bible_get_today, bible_get_reading, or bible_get_card, all of which likely fetch reading content.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds nothing beyond this — no statement about whether the result is the full catalog, whether it is paginated, or how large it is. With annotations doing all the work, the description contributes no extra 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 short fragments where one sentence would do: the first two restate the name and title, and the third is generic toolset boilerplate ('Bible: daily readings, plans, search and passage lookup') that describes other tools rather than this one. The result is duplication plus off-target content rather than front-loaded useful 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?

For a zero-parameter, read-only list tool with no output schema, the description is minimally complete: the agent knows it returns curated daily readings and plans. What is missing is how this catalog relates to the per-item retrieval siblings, which is the one thing an agent needs to choose correctly among them.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description neither misrepresents nor needs to document any inputs.

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 says it returns 'All curated daily readings and plans,' which conveys the resource and scope. However, it largely restates the tool name and title ('bible_list_readings' / 'All curated daily readings and plans') without a distinct verb framing. It also never distinguishes itself from the near-identical siblings bible_get_reading, bible_get_today, and bible_search_readings.

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 when-to-use guidance is given, and no alternative is named. An agent must infer on its own whether to call this versus bible_get_reading (single reading), bible_search_readings (filtered lookup), or bible_get_today (today's entry). The trailing phrase 'search and passage lookup' actually describes sibling tools, which adds confusion rather than 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 readOnly, idempotent, closed-world, non-destructive behavior. The one added behavioral fact is 'best match first', which usefully signals ranked rather than chronological results, but the description says nothing about result count, matching semantics (literal vs fuzzy), or pagination.

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?

It is short and the core purpose is front-loaded, but the leading 'Bible Swipe.' tagline duplicates the title and the trailing 'Bible: daily readings, plans, search and passage lookup (World English Bible)' is generic product boilerplate that covers sibling tools rather than this one.

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

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

For a single-parameter read-only search with full annotations and no output schema, the essentials are present. Still missing are what a 'reading' is and how many/which results return, which a caller might reasonably need.

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 sole parameter q is documented in the schema with examples ('forgiveness', 'shepherd'). The description adds no parameter-level 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?

The description states a specific verb ('Search') and resource ('curated readings') and adds the ranking behavior ('best match first'). It does not, however, distinguish this from siblings like bible_list_readings or bible_get_reading, which an agent must infer are non-search alternatives.

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

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

There is no explicit when-to-use guidance or named alternative. The agent must infer that this is the query-based tool versus bible_list_readings (browse) or bible_get_passage (lookup), but the description never says so.

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), yet the description adds substantial behavior: English-language filtering, one-per-author and one-per-series dedup, ordering by picked_from (shelf before subjects), popular-over-obscure preference, and explicit genre exclusions for novels. This is exactly the kind of context annotations cannot convey.

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 and usage examples, and every clause carries information (dedup rules, ordering, exclusions). It is a dense block that borders on a wall of text, which slightly hurts scanability, but nothing 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?

With no output schema, the description still explains the shape of results via the picked_from/because conventions, and it covers all five optional parameters. An agent has everything needed to call it and interpret the response.

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, but the description adds real meaning: it clarifies that title accepts common informal titles ('1984', 'The Sorcerer's Stone') and that same_author controls whether other books by the author are excluded by default. That goes beyond the plain field definitions.

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 ('find similar books') and pins the scope to 'books like one the user enjoyed, or for a genre'. An agent can distinguish it from bookslikethis_get_book and get_author_books without opening a 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?

Gives concrete trigger examples ('books like The Martian', 'a good cosy mystery') and tells the caller to 'give title or subject', which is clear usage context. It does not, however, explicitly compare against the sibling tools get_book/get_author_books, so there is no when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description's only additional behavioral fact is the 'newest first' ordering. It says nothing about result size, pagination, or whether an unknown author returns empty.

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 short, front-loaded sentences with no fluff. The opening 'Books Like This.' merely restates the title/name and earns no place, which is the only real inefficiency.

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

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

For a simple read-only lookup with no output schema, the agent has everything needed to invoke it: what it returns (an author's books), their ordering, the required parameter, and intent examples. Minor gaps on result volume and no-result behavior are acceptable here.

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% – both 'author' and 'country' (with its US/GB/IE/CA/AU values) are documented in the schema. The description adds no parameter-level detail beyond the example author names. Baseline 3 is correct when the schema does the heavy lifting.

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+resource: it lists an author's books, ordered newest first. Clear and distinct from bookslikethis_find_similar_books and bookslikethis_get_book, but the sibling relationship is never made explicit, so the agent must infer the difference.

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?

"Use for 'what has Andy Weir written?' or 'Sally Rooney's books'" gives concrete user-intent triggers that make the when-to-use condition clear. It stops short of naming alternatives or stating when NOT to use it (e.g. for a single title, use get_book).

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 safety (readOnly, idempotent, non-destructive, closed-world). The description adds genuine value beyond them: the screen_checked=false caveat explains a conditional failure mode where film/TV status is unknown, and 'Misspellings are fine' signals input robustness.

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 and examples are front-loaded and the screen_checked caveat is placed last, which is good ordering. However, the opening 'Books Like This. A book's details and any film or series made from it.' restates the title verbatim, which is redundant padding.

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?

There is no output schema, so the description carries the return-value burden, and it does explain that the tool returns book details plus adaptation status, including the unknown-status edge case. For a simple single-item lookup this is nearly complete, though the exact response shape is not described.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters with constraints and enum-like values for country. The description only adds the misspelling-tolerance note for title, which is marginal beyond what the schema provides – 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 states a specific verb and resource – retrieving a book's details plus any film/series adaptation – which is distinguishable from the sibling tools find_similar_books and get_author_books. It does not explicitly name those siblings, but the single-book framing makes the scope clear.

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?

Concrete trigger phrases ('tell me about Project Hail Mary', 'is The Name of the Wind being made into a film?', 'how long is Dune?') give clear usage context, including the adaptation-check angle. It stops short of contrasting with alternatives like find_similar_books or get_author_books, so no exclusions are 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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds genuine value: it discloses the return artifact (an .ics with an all-day event, steps and official link), the alert schedule (9am the day before and 9am on the day), and that 'Nothing is stored'. No return format on payload structure beyond that, but that is minor.

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 and informative, with the deliverable and behavior described crisply. The leading 'Cancel My Sub.' restates the app/title and the reminder phrase is repeated from the title, which is minor redundancy but not damaging.

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

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

With no output schema, the description correctly carries the burden of describing the return artifact and its contents, and it does so. Nothing critical is missing for an agent 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 description coverage is 100%, so the schema already documents country, service and renews_on fully. The description only implies that renews_on is required for use and adds no syntax or format detail beyond the schema, so it sits at the 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 specific verb and resource: it generates a calendar (.ics) reminder for the last safe day to cancel a subscription. It is clearly distinguishable from the sibling cancelmysub_get_cancel_steps, which returns steps rather than a calendar artifact.

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 triggering condition – the /v1/cancel endpoint surfaces this as add_to_calendar whenever renews_on is given and the day hasn't passed – which tells the agent when this is relevant. It stops short of explicitly naming sibling tools or stating when not to use it.

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

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

Annotations already declare the safe read-only/idempotent/non-destructive profile. The description adds genuine behavioral context beyond that: it returns the official page, steps, catches and a cheaper option, and explains the region/uk_rules behavior including the 'US only' edge case for UK callers.

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-loads the purpose then supplies illustrative examples and return/region details. The opening 'Cancel My Sub. How to cancel one subscription.' largely restates the name and title, and the six-query list is somewhat heavy, but the content still earns most of its space.

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

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

For a read-only tool with no output schema, the description covers intended use, what is returned, and a regional edge case. Missing only explicit fallback behavior for unknown services and sibling routing, which keeps it short of a 5.

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?

With 100% schema description coverage, the schema already documents country, service and renews_on. The description echoes country/region behavior and mentions the derived cancel_by and add_to_calendar outputs, but adds little parameter syntax or meaning beyond what the schema provides. 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?

States a specific verb+resource (get the cancel steps for one subscription) and reinforces it with concrete query examples like 'how do I cancel Netflix?'. It is clearly distinguishable from siblings such as cancelmysub_list_services and cancelmysub_get_cancel_reminder.

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 'Use for ...' phrasing with six realistic queries makes the intended trigger scenarios explicit and easy to match. However, it never names when NOT to use it or routes the agent to alternatives (e.g., list_services when the service name is unknown), so routing guidance is incomplete.

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 description is free to add value — and it does, disclosing the return shape: a likely service, a small candidate set with check-locations for Apple/Amazon/Google/Microsoft, or a match:purchase classification for one-off orders. This output variability is exactly the kind of context annotations cannot convey.

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 two opening fragments ("Cancel My Sub. Which subscription is this charge?.") merely restate the tool name and title and earn no place. The remainder is information-dense, but the "Returns..." sentence is a run-on that mixes several output cases in one breath.

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 one-parameter tool with no output schema, the description covers the need: what to pass, what comes back, and the mandated follow-up call. Only minor gaps remain, such as what happens for a charge that matches no known service.

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?

With a single parameter at 100% schema coverage the baseline is 3, but the description goes further by supplying real-world example values (statement-form merchant strings) that illustrate the expected input format beyond the schema's "The charge as it appears on the statement" 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 action (identify which subscription a statement charge belongs to) with concrete example inputs like "APPLE.COM/BILL" and "DD *DOORDASH DASHPASS". It is clearly distinguishable from siblings such as list_services and get_cancel_steps, and it explicitly hands off to getCancelSteps as the follow-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?

"Use for ..." plus three representative charge strings gives a clear triggering context, and the closing "Then call getCancelSteps" establishes the sequencing with a sibling. It stops short of stating when NOT to use it or pointing to list_services as an alternative for browsing known services.

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, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds one piece of non-obvious context: it also returns FTC click-to-cancel rule status and UK rules (uk_rules). That is useful but thin, and no return shape or pagination is described.

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 first two sentences ('Cancel My Sub. Every subscription Cancel My Sub covers.') restate the name and title with no added information, which is waste before the genuinely useful usage examples and rules-status note.

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

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

For a simple read-only listing tool with no output schema and fully-documented optional params, the description covers purpose, trigger queries, and an unexpected extra return payload. Nothing critical for calling it correctly is missing.

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

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

Schema description coverage is 100% with only two optional params, so the schema already fully documents country and category. The description adds no syntax or filtering semantics beyond what the schema provides, making the baseline 3 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?

States a specific resource (every subscription Cancel My Sub covers) and the example phrasings ('which subscriptions can you help me cancel?', 'what gyms do you know?') make the listing intent unambiguous. It does not explicitly contrast with siblings like get_cancel_steps, but the verb+resource is clear.

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?

Provides explicit trigger phrasings ('Use for...'), which is genuine usage context rather than inference. There are no exclusions or named alternatives, so it stops short of 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description's job is to add beyond that. It usefully discloses that prices are checked live, localized to the shopper's country/currency, and drawn from a named set of retailers. However 'checked live' from external marketplaces sits in tension with openWorldHint=false, and no rate-limit, caching, or fallback behavior is described.

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, but the first two restate the title ('Cheapest Price. Lowest current price for a product, with compare links') and the third opens by repeating 'The lowest current price for a product' a third time. The genuinely new information (source retailers, live check, geo/currency localization) only appears after that redundancy.

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

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

With no output schema, the description carries the burden of describing returns and does so adequately: prices in the shopper's currency plus comparison links to Amazon and local shops. It is reasonably complete for a single-purpose lookup, missing only guidance on failure/empty-result 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 q, used, and country are already fully documented and the baseline is 3. The description reinforces that results are localized to the shopper's country and currency and that eBay can include used items, but adds no syntax or format detail the schema lacks.

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+resource (lowest current price for a product) and names the concrete sources (eBay, Best Buy in the US, Amazon, local shops) plus compare links. This clearly separates it from same-domain siblings like medbillcheck_check_price (medical) and pricedropback_check_price_drop_claim (promo claims).

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 (query a product to get the cheapest live retail price) but the description never states when to use this versus a sibling, nor any exclusions or prerequisites. No alternative tool is named for a near-miss query.

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). The description adds genuinely useful behavior the annotations cannot: fares are cached from what Aviasales travellers found in the last 48 hours, and the live price appears only on the booking page. That freshness caveat is exactly the kind of context an agent needs when reporting prices.

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 core purpose, but the second sentence ('Cheap flights from any city, to one place or anywhere, with the cheapest days to fly') largely restates the first and the title. The price-freshness sentences do earn their place; the middle sentence does not.

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?

There is no output schema, so the description carries the burden of explaining returns. It implies a list of cheapest days but never states the shape (dates plus prices, currency, whether round-trip or one-way). Adequate but leaves an agent guessing about the response structure.

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 four parameters (from, to, month, country) are already documented in the schema, including the month format and the country-for-currency rule. The description adds no parameter-level detail beyond that, 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?

States a specific verb+resource: cheapest departure days for a route in a given month. An agent can tell it returns day-level pricing rather than actual itineraries. It does not explicitly differentiate from the sibling faredeals_find_deals, 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?

No when-to-use guidance, no prerequisites, and the sibling faredeals_find_deals and faredeals_look_up_place are never mentioned. The phrase 'from any city, to one place or anywhere' hints at flexibility but gives no routing rule for choosing this tool over its neighbours.

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, so the safety profile is covered. The description adds only a cryptic note that "the say field is a ready-made answer," without explaining where that field comes from or what the response looks like. Notes about halted/empty results are absent, so value-add is modest.

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 size is appropriate and the core purpose is front-loaded. But the trailing sentence about the "say field" is confusing, references an undefined return field, and does not earn its place — it reads as vestigial text rather than useful guidance.

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

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

There is no output schema, so the description carries the burden of explaining return values, yet it only vaguely gestures at a "say field" without describing result structure or the deal fields. For a nine-parameter fare-search tool, that leaves the agent unable to anticipate what comes back.

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 all nine parameters (including the nuanced `from`/`to` state hints and `country` currency behavior) are already documented. The description repeats the from/to concept without adding syntax or format details, 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?

States a clear verb and resource: finding cheapest recent fares from a city to a place or anywhere. The scope ("recent fares") is specific. However, it does not differentiate itself from sibling faredeals_cheapest_dates, leaving the agent to guess which fare tool fits a given 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?

There is no when-to-use or when-not-to-use guidance, and no mention of the sibling faredeals_cheapest_dates or faredeals_look_up_place. The only usage hint is an implicit default (`to` = anywhere) carried by the schema, not the description.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful data-freshness context ('cheapest Aviasales travellers found in the last 48 hours', 'live price is on the booking page'), but does not explain return shape or how the code is normally used downstream.

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 is front-loaded, but two of the four sentences are fare-marketing copy ('Cheap flights from any city, to one place or anywhere...') that does little to help an agent invoke a place-lookup. Moderate waste for a one-parameter tool.

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?

There is no output schema, so the description carries some burden for explaining returns; it partially does so via the fare-freshness and booking-page notes, but never clarifies what a lookup actually returns (a resolved code, a list of matches). Adequate but with a clear gap for a param-only tool.

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

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

With a single parameter and 100% schema description coverage, the schema already documents the `q` argument with an example ('Lisbon or LIS'). The description adds no meaning beyond that, so the baseline of 3 applies.

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

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

The description clearly states a specific verb and resource: 'Look up a city or airport code,' matching the title. However, the following sentence pivots to flight-deal marketing ('Cheap flights from any city... cheapest days to fly'), which blurs whether this tool resolves a place or returns deals, and it never distinguishes itself from siblings faredeals_find_deals or faredeals_cheapest_dates.

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 guidance on when to use this tool versus the sibling faredeals_find_deals or faredeals_cheapest_dates, even though a place lookup is the obvious prerequisite for those. No prerequisites, sequencing, or exclusions are 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 readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds a behavioral fact beyond them — 'Without a type, returns every source' — i.e., the default result-set breadth when no type is supplied.

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 purpose and default behavior are front-loaded, and the example-query list earns its space by mapping colloquial questions to a structured type parameter. It is a single long sentence, but there is no filler.

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

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

For a two-optional-parameter, read-only lookup with no output schema, the description supplies purpose, representative triggers, default behavior, and UK routing — everything an agent needs 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 description coverage is 100%, so the schema already explains both 'type' (with everyday/UK word mappings) and 'country' (GB/UK gives UK services, defaults to caller's country else US). The description's '(UK with country=GB)' largely restates that same schema guidance rather than adding new semantics, 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?

States a concrete verb and resource (find official sources of lost/owed money) and scopes it as 'Federal and other official places to look, by type', which implicitly distinguishes it from the sibling findmymoney_get_state_search. The example queries make the coverage of the tool unambiguous.

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 eight quoted example questions give a very clear picture of when to invoke it (old 401k, unclaimed refund, lost bonds, deceased relative, UK pension/Child Trust Fund). It does not name the sibling findmymoney_get_state_search or say when this tool is the wrong choice, so it stops short of explicit alternatives.

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

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

Annotations already declare the read-only, idempotent, non-destructive safety profile, so the bar is lower. The description adds genuinely useful behavioral context beyond them: the exact return payload (official link, search_url, MissingMoney.com, tips, claim checklist, scam warning) and the multi-state output layout (first state at top level, rest in more_states).

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 purpose, then examples, then return values, all directly relevant. Slightly padded by restating the title ("Find My Money. A state's official unclaimed property search.") and by a long run of quoted examples, but nothing is wasted.

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

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

With no output schema, the description carries the burden of explaining returns and does so, listing the payload and the multi-state structure. It is close to complete for a two-parameter read tool; only the sibling relationship is left unaddressed.

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 (state, country) are already well documented in the schema, making 3 the baseline. The description adds only a small increment via the multi-state output note, no syntax or format detail beyond what the schema already 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?

States a specific verb+resource and scope: retrieving a state's official unclaimed property search, with concrete query examples that pin down the intent. It does not, however, distinguish itself from its sibling findmymoney_get_sources, which is the natural alternative an agent might confuse it with.

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 quoted example phrasings ("do I have unclaimed money in Ohio?", "I've lived in Ohio, Texas and California, where do I look?") give clear triggering context for when to use the tool, including the multi-state case. There is no explicit when-not guidance or routing to the sibling tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context by enumerating what is returned (positions, form, goals, this season's meeting, next fixture date) and by fencing off betting advice, though it says nothing about pagination, latency, or error behavior.

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 clauses, front-loaded with the purpose, then the example trigger, then the payload, then the scope limit. The redundant 'Form Guide.' opener is the only filler, and every other phrase carries 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?

With no output schema, the description must convey what comes back, and it does so by listing positions, form, goals, head-to-head meeting, and next fixture date. The only gap is that the legacy team1/team2 aliases and the country side-effect (US Eastern kick-off lines) are left entirely to the schema.

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

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

Schema description coverage is 100%, so the schema already documents home, away, country, and the legacy team1/team2 aliases, which sets the baseline at 3. The description adds no parameter-level meaning — it never clarifies the home/away roles, the legacy alias behavior, or what the country flag does — so it cannot rise above baseline.

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

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

The description names a specific operation (comparing two clubs side by side) on a specific resource (two teams about to meet), and the sample query 'Arsenal v Leeds, how do they compare?' makes the intent unmistakable. It is clearly distinguishable from formguide_get_team (one club) and formguide_get_table (league-wide) without opening any 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?

It gives a concrete trigger scenario ('Arsenal v Leeds, how do they compare?') and states the scope boundary 'stats only, not betting advice'. It stops short of naming alternatives such as formguide_get_fixtures or formguide_get_team for single-side questions, so there is no explicit when-not guidance.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the default scope is the Premier League when no team or league is given, which an agent would otherwise have to guess.

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

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

Three short sentences, front-loaded with purpose, then usage examples, then the default behavior. The leading 'Form Guide.' fragment merely restates the title and is the only wasted token.

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 four-parameter, zero-required read tool this is nearly complete: purpose, examples, default scope and the optional country/time behavior are all implied. The lack of an output schema means return shape is only loosely conveyed, but fixture listings are self-explanatory.

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 schema already documents days, team, league and country in more detail than the description (including the 404 on unknown leagues and the international-break fallback). The description's only parameter-relevant statement is the no-argument default, 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?

States a specific verb and resource ('Upcoming fixtures') and clearly scopes it to a club or league, which distinguishes it from formguide_get_results, formguide_get_table and formguide_compare_teams without opening any 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?

Gives concrete usage contexts ('who do Liverpool play next?', 'what's on in La Liga this weekend?') and states the fallback when neither team nor league is supplied. It never explicitly excludes siblings such as get_results, but the intent is unambiguous.

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 profile is covered. The description contributes the fallback behavior (no team/league yields Premier League), which the agent needs to predict output without arguments.

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, purpose and scope front-loaded, examples placed to drive selection, and the default stated last. No filler; each sentence earns its place.

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

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

A read-only, zero-required-parameter tool with fully documented schema and clear annotations; the description accounts for the no-argument case and typical queries, so an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3, and the description adds real value by disclosing the default behavior when neither team nor league is supplied (defaults to Premier League). It doesn't add format or matching semantics beyond the schema, but the default is behavior the schema doesn't carry.

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 (latest results) and disambiguates scope: 'for a club, or the last round of a league.' It implies distinction from siblings like formguide_get_fixtures and formguide_get_table, but doesn't name them explicitly, so an agent must infer the boundary.

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 concrete trigger examples ('how did Chelsea get on?', 'what were the Serie A results?') and states the no-argument default (Premier League). It stops short of routing guidance against siblings such as fixtures or standings, so it's clear context without explicit alternatives.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuinely new domain behavior: points include official deductions and deducted clubs carry a points_deducted field, which is not derivable from annotations and is valuable since there is no output 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?

Very tight: purpose and example triggers come first, with the points-deduction caveat last. The 'Form Guide.' fragment mildly restates the title, a minor redundancy that keeps it from a full 5.

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-required-param, read-only lookup with a fully documented schema and no output schema, the description supplies everything needed: intent, trigger examples, and the one non-obvious return-value quirk (points_deducted). Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, and the schema already documents accepted league names, variants, the 404 behavior and the default. The description's league references (Championship, La Liga) merely echo schema values, adding no syntax or constraint detail beyond it, 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 the resource unambiguously ('League table') and reinforces it with two natural-language user queries ('show me the Championship table', 'who is top of La Liga?'). This cleanly separates it from siblings like formguide_get_fixtures, formguide_get_results and formguide_get_team without needing to name them.

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 conveyed through concrete example phrasings that map directly to the tool's intent, giving an agent a clear trigger match. It stops short of saying when NOT to use it or naming an alternative sibling for adjacent needs, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond the title text it repeats verbatim — nothing about return format, freshness of form data, or fallback behavior when a club is unknown.

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?

Very short and front-loaded: the resource is stated first, then three concrete example phrasings. The main flaw is duplicating the title verbatim in the first sentence, which is slack rather than added value.

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

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

For a read-only lookup with no output schema, the description does name the three things returned (position, recent form, next games), and the schema fully covers inputs. It is close to complete, though it omits any hint of the response shape or how 'recent form' is represented.

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 fully documents team, q, league and country, including the 404 behavior for unsupported leagues and the deprecation note on q. The description contributes no additional parameter meaning, so the 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 names a specific resource (a club's league position, recent form, next games), which is more than a restatement of the name. It is clear what data is returned, though it does not distinguish itself from siblings like formguide_get_table, formguide_get_results or formguide_get_fixtures, which cover overlapping ground.

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?

Three example user questions ("how are Arsenal doing?", "what's Spurs' form?", "when do Birmingham play next?") imply the intended usage well. However it never states when to prefer this composite tool over formguide_get_fixtures/get_results/get_table, nor any conditions or exclusions, so routing against siblings is left 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 establish the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the description only needs to add context. It usefully discloses that output is one line at a time and aimed at voice, but omits how many cards exist, whether n is bounded, or what 'defaults to today's reading' implies when no reading exists.

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 opens by duplicating the title verbatim ('Gita Scroller. Today's reading one line at a time, for voice..'), including a doubled period, then appends a catch-all feature list that relates to sibling tools rather than this one. It is not front-loaded around what a caller does with this specific tool.

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 paged read tool with three optional parameters and no output schema, the agent still lacks the essentials: how many cards a reading contains, whether to advance n sequentially, and how this differs from gita_get_today. Annotations cover safety, but the call-shape gaps are real.

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 n, date, and reading with defaults. The description adds the notion of 'one line at a time' that maps loosely to n, but contributes no additional format or constraint detail. Baseline 3 is correct when the schema carries the parameter burden.

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 identifies the resource (today's Bhagavad Gita reading) and the paging granularity ('one line at a time'), which is more specific than a bare name restatement. However, the second sentence is a generic app-level blurb covering many sibling tools ('daily verses, plans, search and verse lookup; whole books from the Library'), so it does not clearly distinguish gita_get_card from gita_get_today, gita_get_reading, or gita_get_chapter.

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 hints at a context ('for voice') but never states when to use this tool versus gita_get_today, gita_get_verse, or gita_get_reading. There is no guidance on how to paginate through cards or how to know when the sequence ends, which is exactly what an agent needs for a paged 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds genuine value by specifying the content delivered (Sanskrit, transliteration, English), which matters absent an output schema. It adds nothing about size, pagination, or handling of invalid chapters, keeping it at a middling 3.

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 first sentence restates the title verbatim, and the second sentence is a noisy run-on listing app features unrelated to this call. Structurally the relevant content is front-loaded, but a large fraction of the text does not earn its place for this specific tool.

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 single-parameter read tool with full annotation coverage and full schema coverage, the description is adequate. Its main gaps are the absence of any return-shape specifics (chapter length, verse count) and no sibling differentiation, which are tolerable but leave the definition only minimally 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 description coverage is 100%: the single 'chapter' parameter is documented in-schema with a 1-18 description and min/max bounds. The description contributes no additional parameter meaning, so the baseline 3 for fully covered schemas 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?

The description does state a specific resource ('a whole chapter in Sanskrit with transliteration and English'), so the core purpose is discernible. However, the trailing clause ('daily verses, plans, search and verse lookup; whole books from the Library') describes the broader app or sibling tools rather than this tool, muddying rather than sharpening the purpose. It never distinguishes this from gita_get_verse, gita_get_reading, or gita_read_book.

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 guidance and no named alternative. The mention of 'search and verse lookup' and 'read a passage at a time' gestures at other capabilities but does not tell the agent when to pick a whole chapter versus a verse or a reading. The agent must infer selection criteria entirely.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds no behavioral context beyond that (no mention of what a 'reading' yields, plan-name resolution behavior, or errors for unknown ids), so it earns little credit above the annotations.

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

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

The first two sentences duplicate the title, and the remainder is app-level marketing copy rather than tool-specific function. It is not front-loaded with what this tool does, and much of the text does not earn its place.

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

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

For a simple one-parameter read tool with no output schema, the description is minimally adequate, and the schema covers the id semantics. However, it omits anything about how 'reading' vs 'plan' output differs or what 'line by line' returns, leaving a gap an agent would notice.

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?

With a single parameter and 100% schema description coverage, the schema fully documents the id field including that it accepts a reading/plan id or a plan name like 'japji'. The description adds nothing beyond this, so the high-coverage 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 largely restates the app tagline and the tool title ("One reading or plan, line by line") rather than stating a distinct verb+resource for this tool. The line "Bhagavad Gita: daily verses, plans, search and verse lookup" describes the whole app's feature set, which overlaps with siblings like gita_get_today, gita_search_readings, and gita_get_verse, so it does not distinguish this tool from them.

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 when-to-use guidance or alternative is given. An agent cannot tell from this text whether to call gita_get_reading, gita_get_today, or gita_read_book for a given request; the sibling differentiation is absent.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds one genuinely useful behavioral fact — the output matches what the app displays today — but says nothing about the return shape (verse text? chapter/verse refs? length of the passage).

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 leading "Gita Scroller." restates the title and the second sentence is wholesale app-level marketing that does not describe this tool. Only the middle clause ("Today's reading, line by line") earns its place, so the definition is largely padding.

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-required-param, read-only, no-output-schema tool the bar is low, but the agent still cannot tell what "today's reading" contains (how many verses, which chapter, what the payload looks like) or how it differs from gita_get_reading for a non-today date. Adequate but with a clear 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 coverage is 100% and the single optional date parameter is fully documented in the schema (YYYY-MM-DD, defaults to today UTC). The description adds no meaning beyond that, 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 phrase "Today's reading, line by line" does name a specific resource and format, but the surrounding text ("Gita Scroller", "daily verses, plans, search and verse lookup; whole books from the Library") describes the whole app rather than this tool, making the boundary against gita_get_reading, gita_get_card and gita_list_readings fuzzy. It is not a tautology, but it is a vague framing polluted by product copy.

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 statement of when to call this versus gita_get_reading (arbitrary date) or gita_list_readings (index of readings). The mention of "plans, search and verse lookup" gestures at other capabilities without routing the agent to the sibling tools that provide them.

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 a safe, idempotent, read-only, non-open-world operation, so the safety profile is covered. The description usefully adds that results come in Sanskrit plus transliteration and English, but says nothing about pagination, missing-verse behavior, or error handling.

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 first sentence is front-loaded and earns its place, but the second sentence is generic app marketing spanning five features and dilutes focus. The title is also truncated ('A verse or range (e.g'), adding noise.

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 2-parameter, read-only tool with full schema coverage and no output schema, the description is close to sufficient: it names the inputs' format and the returned content languages. What is missing is routing guidance against the many gita siblings.

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 chapter (1-18) and verse are documented in the schema, and the description adds only the '47-51' range format which the schema already supplies. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

The first sentence states a specific resource — a verse or range (e.g. 47-51) — and the return content (Sanskrit with transliteration and English). It is clear what the tool retrieves, though it never contrasts itself with gita_get_chapter or gita_get_reading, which also return scripture text.

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 second sentence is app-level blurb ('daily verses, plans, search and verse lookup; whole books from the Library') that names sibling capabilities without saying when to call this tool versus them. No exclusions or conditions are given.

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, openWorldHint=false and destructiveHint=false, so no credit is due for repeating a safe-read posturing. The description adds no behavioral context beyond the title, such as ordering, coverage of the library, or pagination.

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?

'read a passage at a time' is stated twice and the sentence about daily verses, plans, search and verse lookup is unrelated padding. The remaining content is title-level rather than information a calling agent can act on.

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 enumeration tool with no output schema, the description should at least convey what a caller receives (e.g., book identifiers/titles to feed into gita_read_book). It supplies none of that and instead repeats marketing copy, leaving the calling contract underspecified.

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

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

The tool takes zero parameters and the schema coverage is 100%, so there is nothing for the description to clarify at the parameter level; baseline 4 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 largely restates the title ('Gita Scroller. The whole books in the Library that can be read a passage at a time') and never states a clear verb like 'list' or says what the list contains. It also lumps in unrelated feature copy ('daily verses, plans, search and verse lookup') that belongs to sibling tools, muddying the purpose rather than sharpening it.

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

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

No when-to-use guidance and no alternative is named, even though siblings like gita_search_readings, gita_get_verse, and gita_read_book clearly cover the other functions the description mentions. The agent is left to infer that this tool only enumerates available books.

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 (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description only needs to add context. It adds the 'All curated' scoping notion but nothing about the shape or volume of the list, and its second sentence advertises unrelated capabilities, diluting rather than clarifying behavior.

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 first sentence merely repeats the app name and title, and the second is a run-on catalog of the entire product rather than a front-loaded statement of this tool's output. Short, but neither sentence is well targeted at the specific operation.

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 no-param read-only list, the description still leaves the agent unsure what a 'reading' or 'plan' actually is, whether the result is paginated, and how it differs from the other Gita list/lookup tools. With rich annotations and no output schema, the description needed to carry more scope information and does not.

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

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

The tool takes zero parameters and the schema is an empty object, so there is no parameter semantics to explain; baseline of 4 applies. The description adds no misleading parameter expectations.

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 title and opening sentence state a recognizable verb+resource (list all curated daily readings and plans), and 'All' implies full-list scope versus the single-item siblings gita_get_today/gita_get_reading. However, the second sentence describes app-wide capabilities (daily verses, search, verse lookup, whole books, reading a passage) that belong to sibling tools, blurring what this specific tool returns.

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 indication of when to choose this over gita_get_today, gita_list_books, or gita_search_readings. The trailing clause about 'search and verse lookup' and 'read a passage at a time' actively points at other tools without naming them, leaving the agent to guess the selection 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorldHint=false, so safety is covered. The description does add one genuine behavioral detail: 'it carries on into the next chapter,' useful for a scroller-style read. However, it says nothing about rate limits, return format, or how the ref/n/section interplay behaves at boundaries.

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 opens by restating the title verbatim ('Follow next for the next passage; it carries on into the next chapter') and then lists features that belong to other tools, which is noise rather than front-loaded signal for this tool. The only tool-relevant phrase is buried at the end.

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 4-parameter read tool with no output schema, the description should clarify how book/section/n/ref compose and what a call returns (a passage card?), especially given its scroller/continuation framing. Instead it omits any of that and spends its length on app marketing and sibling features.

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 all four parameters (book, section, n, ref) are fully documented in the schema, including the precedence rule that ref overrides section and n. The description adds no parameter meaning beyond the schema, 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 signals a read operation ('read a passage at a time') over a book/passage resource, but the first two sentences are app-flavored ('Gita Scroller', 'Follow next') rather than stating the action. It also lists unrelated capabilities (daily verses, plans, search, verse lookup) that belong to sibling tools, muddying what this specific tool does. The verb+resource pair is discernible but not crisply stated.

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 guidance on when to use this tool versus clear siblings like gita_get_reading, gita_get_verse, or gita_get_chapter. The 'read a passage at a time' hint is the only implicit usage cue, and no alternatives or exclusions are named.

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, so the safety profile is covered. The description adds one genuinely useful behavioral trait beyond that: results come back 'best match first'. It says nothing about result count, pagination, or what a 'reading' record contains.

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?

It is short and front-loads the actual purpose, but the second sentence is app-level marketing boilerplate that lists capabilities this tool does not expose (daily verses, plans, whole books) and therefore does not earn its place here.

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

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

The tool is simple (one required string param, no output schema, annotations covering safety), so the definition is minimally viable. It still leaves ambiguous what corpus 'curated readings' covers and what fields a result carries, which matters when the sibling set includes both list and get variants.

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's own description already supplies usage examples ('duty or fear'), so the description carries no additional burden. It adds no extra semantics about matching behavior (substring, fuzzy, multi-word) beyond the schema baseline.

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

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

The first sentence gives a specific verb and resource: search the curated readings with best-match ordering. However, the second sentence is generic app boilerplate about verses, plans, verse lookup and whole books, which describes the whole Gita Scroller app rather than this tool, so it does not distinguish this search tool from siblings like gita_list_readings or gita_get_reading.

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 statement of when to use this versus gita_list_readings (browse the full index) or gita_get_reading (fetch a specific item by id). The agent must infer the search-vs-list distinction from the tool 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, non-open-world), so the bar is lower. With no output schema, the description earns credit by disclosing exactly what comes back — every line of an Ang, in Gurmukhi plus transliteration plus English — which tells the agent the shape of the payload. It stops short of pagination or size hints.

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 repeats the title verbatim in its second sentence and opens with a soft metaphor, then ends with a broad server-wide capability menu that is not specific to this tool. The operational content is present but padded by duplication and off-topic 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?

For a simple one-parameter read operation, annotations fully cover behavior and the schema fully documents the parameter, so the description's main remaining duty is return content — which it supplies. It is nearly complete, missing only pagination or volume expectations for a 1430-page corpus.

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%: the single 'ang' parameter is already documented as the page (1 to 1430) of Sri Guru Granth Sahib, including range and meaning. The description adds nothing beyond what the schema states, 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 second sentence states a specific result — every line on an Ang in Gurmukhi with transliteration and English — so the verb (retrieve lines) and resource (Ang) are clear. The opening metaphor 'Scroll the Gurbani' is vaguer, and the description never explicitly distinguishes this page-lookup from siblings like gurbani_get_shabad or gurbani_get_reading, but the resource is distinct enough to differentiate.

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 explicit when-to-use or when-not-to-use guidance and no named alternative. The trailing menu ('daily shabad, plans, search, Ang and shabad lookup; whole books') gestures at other capabilities but does not tell the agent which sibling to prefer for a shabad lookup versus a page lookup, leaving routing 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only the vague 'one line at a time' framing and discloses nothing about what a 'card' contains or how scrolling/pagination behaves. It does not contradict annotations, but adds little beyond them.

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

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

The text repeats the title verbatim, contains a doubled period ('voice..'), and appends a generic multi-tool suite blurb ('daily shabad, plans, search, Ang and shabad lookup; whole books...') that has no bearing on calling this tool. Wording is wasted rather than front-loaded with useful specifics.

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 schema is complete and annotations cover the safety profile, and there is no output schema to explain, so the core requirements are met. However, for a tool whose only distinguishing concept is 'a card,' the description never defines that concept or routes the agent away from sibling tools, leaving a real 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%, so all three parameters (n, date, reading) are fully documented in the schema with defaults and formats. The description adds no syntax or format detail beyond it, 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 first sentence, 'Scroll the Gurbani. Today's reading one line at a time, for voice..', essentially restates the title verbatim and never clarifies that the tool returns a paginated 'card' of today's reading. It offers no differentiation from close siblings like gurbani_get_today or gurbani_get_reading. The second sentence is generic suite boilerplate covering all Gurbani tools rather than this one.

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 explicit when-to-use or when-not-to-use guidance and no sibling is named as an alternative. The phrase 'for voice' hints at a voice-use context but does not tell the agent when to pick this over gurbani_get_today or gurbani_get_card's peers. Usage must be inferred entirely.

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, destructiveHint, and openWorldHint, so the safety profile is covered. The description adds a small amount of behavioral context with 'line by line' and 'read a passage at a time', hinting at incremental/passage-based output beyond what annotations provide, but does not describe return format, pagination mechanics, or error behavior.

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 opens with a vague slogan ('Scroll the Gurbani') rather than the core action, then appends a long, run-on third sentence enumerating unrelated Gurbani capabilities. That third sentence does not earn its place for this specific tool and distracts from the narrower purpose. The structure is not front-loaded with the essential distinction.

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 one-parameter read tool with rich annotations and full schema coverage, the description is minimally adequate but leaves gaps. It does not clarify what the tool returns (full reading text, line-by-line stream, or plan metadata) and does not help the agent distinguish it from similar sibling tools. Given the low complexity and safe-read annotations, 3 is the minimum viable score.

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 required id parameter is fully documented in the schema itself. The description only restates that the tool works on 'one reading or plan' without adding format, validation, or lookup rules beyond what the schema already provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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 verb ('Scroll', 'read') and resource ('Gurbani', 'one reading or plan'), but the third sentence lists features of the broader Gurbani namespace (daily shabad, plans, search, Ang and shabad lookup) that belong to sibling tools, muddying what this specific tool does. 'One reading or plan, line by line' is the only truly specific phrase, and it is not enough to clearly distinguish from gurbani_get_shabad or gurbani_read_book.

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 explicit when-to-use or when-not-to-use guidance is provided. The description never names an alternative sibling tool or states the condition under which this tool should be chosen over gurbani_list_readings, gurbani_read_book, or gurbani_get_ang. The usage must be inferred entirely from the schema parameter.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds the useful behavioral fact that the result includes transliteration and English, but says nothing about invalid-id behavior or response size. Adequate with annotations, not rich.

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 statement ('A whole shabad by BaniDB id, with transliteration and English') is well front-loaded. However, it largely duplicates the title, and the second half is app-level boilerplate listing unrelated features ('daily shabad, plans, search, Ang and shabad lookup; whole books from the Library'), which does not earn its place in this tool's description.

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

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

A one-parameter read-only lookup with full schema coverage likely has an output schema absent, so the description's note that it returns transliteration and English is a meaningful completion. Combined with annotations covering safety and idempotency, an agent has enough to call it correctly, though the sibling-boundary information remains thin.

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% for the single 'id' parameter, so the schema fully documents it and a baseline of 3 applies. The description repeats the 'BaniDB id' notion but adds no format, range, or example beyond the schema text.

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 title/description states a specific verb and resource: fetch a whole shabad by BaniDB id with transliteration and English. It is clear what the tool returns, but it never names or distinguishes itself from near siblings such as gurbani_get_ang, gurbani_get_reading, or gurbani_search_readings, so the agent must infer the boundary.

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 explicit when-to-use or when-not-to-use guidance. The phrase 'read a passage at a time' hints at a contrast with passage-level tools, but no alternative is named and no condition for selecting this tool over gurbani_get_ang or gurbani_search_readings is given. The trailing list ('daily shabad, plans, search, Ang and shabad lookup') enumerates other app capabilities rather than routing guidance for 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and non-destructive, so the safety profile is covered. The description adds only 'same as the app shows today' and line-by-line granularity; it says nothing about output shape, number of lines returned, or date-range behavior.

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 second sentence is a catalogue blurb covering the entire Gurbani tool family (shabad, plans, search, Ang, Library books) rather than this tool, so roughly half the text does not earn its place. The opening is front-loaded, but the padding dilutes it.

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 one-optional-param read-only tool with no output schema and full annotation coverage, the definition is minimally viable. It could usefully say what a 'reading' returns and how the date argument interacts with the 'today' framing, but 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?

Single optional parameter with 100% schema coverage, including the YYYY-MM-DD format and the UTC default. The description adds no parameter meaning 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 opening states a clear resource and scope: today's reading, rendered line by line like the app. It does not, however, differentiate itself from close siblings such as gurbani_get_reading or gurbani_get_card, which an agent must guess between.

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 when-to-use guidance, no exclusions, and no routing to alternatives. The tail sentence lists sibling capabilities (search, Ang lookup, Library books) without saying which condition selects this tool over them.

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 no behavioral context beyond that — no statement of what the call returns, ordering, or whether results are cached/static. It is not contradictory, just empty.

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 text is repetitive and poorly front-loaded: 'Scroll the Gurbani' is restated twice and followed by a run-on inventory of unrelated app features. The core purpose is never stated in a leading, scannable clause.

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, no-output-schema tool the description should at minimum state that it returns the list of available books and how that differs from gurbani_list_readings. Instead it leaves the return content and the sibling boundary entirely implicit, which is inadequate given the dense cluster of gurbani_* tools.

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

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

The tool takes zero parameters, which is the baseline-4 case. The empty schema is consistent with a simple catalogue-listing call, and the description neither helps nor harms here.

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 never states a verb like 'list' or 'return'; it opens with the marketing phrase 'Scroll the Gurbani' and then vaguely describes 'the whole books in the Library that can be read a passage at a time.' An agent has to infer from the tool name alone that this returns the catalogue of books, and nothing distinguishes it from siblings like gurbani_list_readings or gurbani_read_book.

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 guidance, no prerequisites, and no mention of alternatives. The trailing sentence lumps together unrelated capabilities ('daily shabad, plans, search, Ang and shabad lookup') rather than telling the agent when this specific tool is the right call versus gurbani_list_readings.

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, destructiveHint=false, so safety is covered. The only added behavioral fragment is 'read a passage at a time', which is a thin hint about consumption granularity and could equally describe gurbani_read_book. It adds little beyond 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?

The text is a fragment run-on: 'Gurbani: daily shabad, plans, search, Ang and shabad lookup; whole books from the Library, read a passage at a time.' Ideas are dumped without hierarchy and the second sentence does not earn its place because it describes other tools' work rather than this one's.

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-param list tool with annotations already carrying the safety profile and no output schema, the description only needs to convey what is returned. It gestures at 'all curated daily readings and plans', but the trailing sibling-capability list muddies the scope and never clarifies the return shape.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate at the argument level; the baseline for a zero-param tool is 4.

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 plus title indicate a listing of all curated daily readings and plans, which is a recognizable verb+resource. However, the second sentence drifts into 'daily shabad, plans, search, Ang and shabad lookup; whole books from the Library', which describes capabilities owned by sibling tools (gurbani_get_shabad, gurbani_search_readings, gurbani_read_book). This blurs rather than sharpens what this specific tool does.

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

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

There is no statement of when to use this tool versus the many gurbani_* siblings. Worse, it names 'search' and 'Ang and shabad lookup' without routing guidance, so an agent may pick this tool for a search or a shabad lookup that belongs to gurbani_search_readings or gurbani_get_shabad.

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, openWorldHint=false and destructiveHint=false, covering the safety profile. The description adds useful continuation behavior ('carries on into the next chapter'), but says nothing about pagination, ordering, or what a passage contains beyond what the schema implies.

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 opening is front-loaded, but the second sentence is a general overview of the whole Gurbani server rather than this tool, mixing unrelated features ('plans, search, Ang and shabad lookup') into a definition that should focus on reading a book passage by passage.

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?

As a read-only tool with no output schema and full schema coverage of its 4 params, the minimum viable information is present. Still, it never explains ordering across chapters/sections or how ref interacts with section for continuation, which would help an agent drive sequential reads.

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 book, section, n, and ref are already fully documented in the schema, including the ref override semantics. The description adds no parameter-level detail, 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 final clause 'whole books from the Library, read a passage at a time' does convey the specific verb+resource, and the title clarifies sequential passage reading. However, it is tangled with a server-level overview ('daily shabad, plans, search, Ang and shabad lookup') rather than a crisp statement of this tool's function, and it never distinguishes itself from gurbani_get_reading or gurbani_get_today.

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?

'Follow next for the next passage' implies sequential reading use, but there is no explicit when-to-use versus the many sibling reading tools (gurbani_get_reading, gurbani_get_ang, gurbani_get_card). An agent must infer which tool to pick with no routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds one genuinely useful behavioral fact beyond the annotations: results are returned best-match first. It says nothing about result count, pagination, or empty-match behavior.

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 title is restated almost verbatim in the first two sentences ('Scroll the Gurbani. Search the curated readings, best match first'), which is pure duplication. The third clause then lumps in unrelated features (plans, Ang lookup, Library, passages) that do not belong to this tool, diluting an otherwise short definition.

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?

There is no output schema, so the description should carry the return behavior, yet it never explains what a 'reading' result contains, how many come back, or whether the search covers only curated readings or the whole corpus. The closing feature list introduces scope ambiguity that a single-purpose search tool cannot afford.

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 itself gives a concrete example ('Japji or humility'), so the description carries no additional burden. The description adds nothing about the query parameter — the phrase 'whole books from the Library, read a passage at a time' describes the family at large, not the 'q' input. Baseline 3.

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

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

The description states a specific verb+resource ('Search the curated readings') with a ranking cue ('best match first'), so the agent knows this is a search tool rather than a lookup. It does not, however, explicitly differentiate itself from sibling lookups like gurbani_get_reading or gurbani_get_shabad.

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 statement of when to use this tool versus the many sibling lookups (gurbani_get_ang, gurbani_get_shabad, gurbani_list_readings, gurbani_read_book). The trailing list of unrelated Gurbani features ('daily shabad, plans, search, Ang and shabad lookup; whole books') muddies rather than guides 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 already declare the safe read-only, idempotent, closed-world profile, so the bar is lower. The description adds useful behavioral context beyond annotations: it returns a verdict, main scholarly views, and halal alternatives, and it recognizes single ingredients and E-numbers.

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

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

The description is front-loaded and appropriately sized, with the domain list earning its place by clarifying scope. The opening 'Halal or Not.' repeats the title and is slightly redundant, but there is little wasted 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 one required parameter fully documented, strong safety annotations, and no output schema, the description supplies the needed return-value context and broad domain coverage. It falls short only by omitting sibling routing and any limitations on question scope.

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

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

The input schema already has 100% coverage for the single required q parameter, including an example question. The description adds scope hints like ingredients and E-numbers but does not add syntax, formatting, or constraints beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool answers any 'is it halal' question and returns verdicts, scholarly views, and alternatives. However, it does not distinguish this generic ask tool from the many specialized halalornot siblings such as check_crypto, check_medicine, check_ingredients, or check_product_by_barcode.

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

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

The description implies usage by listing covered domains, but it gives no explicit when-to-use guidance, no exclusions, and no routing between this generic tool and the specialized halalornot_check_* alternatives. An agent must infer when this broad tool is preferable.

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 safety is covered. The description adds that the tool returns both a functional classification and scholarly views, which is useful content context, but it says nothing about coverage limits, handling of unknown tickers, or response shape.

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 first two sentences ("Halal or Not. Is this cryptocurrency halal?.") duplicate the name and title verbatim and earn no place. The substantive sentence is dense and informative, but the definition is not front-loaded with it.

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

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

With no output schema, the description usefully sketches what comes back (a functional classification plus scholarly views), which is the key thing missing from structured fields. For a one-parameter read-only lookup it is nearly complete, lacking only edge-case 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% for the single 'coin' parameter (name or symbol, with examples), so the schema does the heavy lifting. The description adds no syntax, formatting, or ambiguity guidance beyond what is already structured.

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 second sentence names a specific verb (classifies) and resource (a coin) and enumerates the classification buckets (lending, gambling, meme, stablecoin, staking, general-purpose), which separates it from halalornot_check_fund and halalornot_screen_stock. The opening two sentences merely restate the tool name and title, adding no new information.

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: an agent can infer this is for individual coins versus the fund/stock siblings, but the description never states when to use it, when not to, or names an alternative. No prerequisites or input constraints are given.

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 adds real behavioral context beyond that: it reads the latest SEC holdings report and screens every holding by industry and debt, and explains the UK fallback path. It does not say what happens for unsupported or ambiguous tickers.

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 and the length is justified by the non-obvious resolution logic. The final sentence is dense (a long list of ETF examples and index-holdings fallback) and could be tighter, but every sentence carries 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?

With no output schema, the description should indicate what the agent receives back, but it never states that a halal/haram verdict (or screening rationale) is returned. It also omits error behavior for unknown tickers. The method coverage is good, so it is adequate but has clear gaps for a single-param decision 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 there is only one parameter, so the schema already carries the semantics — baseline 3. The description restates that tickers and Shariah fund names are accepted, which the schema's own description already conveys, so little is added.

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 ('check fund'), names the asset classes covered (fund, ETF, pension fund), and explains the mechanism (Shariah recognition by name/ticker, SEC holdings screening). It implicitly separates itself from halalornot_screen_stock and halalornot_check_crypto by scope, though it never names those siblings as alternatives.

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

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

Usage is implied through the geographic/coverage detail — US-registered funds screened directly, UK-listed ETFs routed via an index-tracking US fund — which tells the agent when this tool can answer. However there is no explicit when-to-use/when-not guidance and no mention of the sibling screen_stock tool an agent might otherwise pick.

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, closed-world behavior, and the description adds meaningful return context (overall verdict, per-school verdicts, flagged ingredients with reasons) that compensates for the missing output schema. It adds little beyond that—no auth, limits, or failure behavior—but against strong annotations this is solid.

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

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

Tight and front-loaded, with the return shape stated up front. The opening fragment 'Halal or Not.' is brand repetition of the title and is the one piece of low-value text, but overall there is little waste.

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 two-parameter lookup with no output schema, the description covers the purpose, input requirement, and return contents adequately. It is slightly under-complete on the context parameter and on how this differs from sibling tools.

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 are documented; baseline is 3. The description reinforces the ingredients format ('exactly as printed') but says nothing about the context enum, so it adds only marginal value 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 (check) and resource (an ingredients list), making the purpose immediately clear. However it does not distinguish itself from close siblings like halalornot_ask_is_it_halal, halalornot_explain_ingredient, or halalornot_check_product_by_barcode, so an agent cannot route confidently from the description alone.

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 or when-not-to-use guidance and no mention of alternatives among the many halalornot_* siblings. The only instruction ('Pass the ingredients exactly as printed on the pack') is an input-formatting note, not usage 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 readOnly, idempotent, non-destructive, closed-world behavior, so the burden is light. The description still adds meaningful context beyond them: the underlying openFDA US-label data source, the specific substances flagged, and the deliberate 'ruling on necessity' framing that prevents users from abandoning prescribed medicine. Only the result format details (e.g. pagination, error behavior) remain unstated.

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 first two sentences ('Halal or Not. Is this medicine halal?.') merely restate the title and tool name and could be dropped. The remaining sentence is dense and front-loaded with the important material, but the redundant lead costs it.

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

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

With no output schema, the description reasonably covers returns by naming ingredient_headline and verdict and describing the headline/say line ordering. For a single-parameter, closed-world read tool with full annotations, the agent has enough to call it correctly, though the response shape is only partially sketched.

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 'name' parameter is documented in-schema as 'Brand or generic name.' The description adds no format, casing, or disambiguation guidance beyond that, so the baseline 3 for a fully-covered single parameter 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?

States a specific verb and resource ('Reads a medicine's active and inactive ingredients from its US label (openFDA) and flags gelatine, alcohol, pig-derived enzymes and heparin'), which cleanly separates it from siblings like check_ingredients, explain_ingredient, and check_product_by_barcode. The data source (openFDA US label) further pins down scope for an agent choosing among halalornot 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?

There is no explicit when-to-use, when-not-to-use, or named alternative among the halalornot siblings. The reader can infer the tool applies to medicines, but nothing routes the agent between this and check_ingredients or explain_ingredient when a query is ambiguous.

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. The description adds a genuine behavioral detail — the Open Food Facts then Open Beauty Facts lookup chain — which explains result provenance, but it omits what happens when a barcode is not found and does not describe rate limits or the verdict shape.

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

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

Three short sentences, front-loaded with the purpose before the mechanism. The opening 'Halal or Not.' fragment largely duplicates the title, which is minor waste, but the rest is efficient.

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?

There is no output schema, so the description carries the burden of conveying return values, yet 'checks its ingredients' does not explain the halal verdict, confidence, or possible error results. For a single-parameter tool this is workable but leaves the agent guessing about output.

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%; the 'barcode' parameter is fully documented in the schema with accepted formats (EAN-13, EAN-8, UPC). The description adds no syntax or format meaning beyond that, 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?

States a specific verb and resource ('check a product by barcode') and even names the data sources and the ingredient check. It is clearly distinguishable from siblings like check_ingredients (ingredient text) and search_products (name search), though it never explicitly contrasts itself with them.

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 barcode-centric phrasing implies the triggering condition (you have a barcode), but there is no explicit when-to-use, when-not-to-use, or named alternative such as check_ingredients for non-barcode input. Usage must be inferred.

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 and non-destructive behavior. The description adds output context with 'Returns the verdict for each school and the reasoning' — valuable since there is no output schema — though it does not mention any limits or input-validation constraints.

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

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

Three short, front-loaded sentences that are easy to scan. The leading 'Halal or Not.' brand fragment slightly duplicates the title, but overall the text is efficient with little waste.

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

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

For a read-only lookup with fully described parameters and no output schema, the definition is nearly complete: it names the resource, gives examples, and sketches the return shape (per-school verdict plus reasoning). The only gap is the absence of any sibling routing or context-enum guidance.

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 are already documented; the description's ingredient examples reinforce the 'name' parameter but add nothing new. The 'context' (food/cosmetic) parameter is not mentioned at all in the description, so the schema carries the full burden there.

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: 'Explain one ingredient or E-number', with concrete examples (E471, carmine, prawns, whey). The singular 'one' implicitly distinguishes it from the bulk halalornot_check_ingredients, but no sibling is named. Clear purpose, no explicit 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?

Usage is implied: explain a single ingredient or E-number. There is no explicit when-to-use guidance, no exclusions, and no mention of the adjacent halalornot_check_ingredients (bulk) or halalornot_explain_schools alternatives, leaving routing 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 establish readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds that output includes the reasoning and halal alternatives, which is modest extra value, but it never explains why a tool that 'answers is it halal' takes no input or what form the answer takes.

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 leading 'Halal or Not.' merely repeats the title and burns space, and the sentence becomes an overstuffed run-on listing every asset category. The core idea (four schools, agreement/difference, reasoning) is front-loaded but padded.

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

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

For a zero-param, read-only, no-output-schema tool the description gives a reasonable sense of what comes back (school-by-school agreement, reasoning, halal alternatives), but it omits any return-shape hint and never reconciles its broad scope with the dedicated check_* siblings, leaving real ambiguity about when this is the right call.

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

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

The schema declares zero parameters at 100% coverage, so there is nothing for the description to document. Baseline 4 applies; the description correctly implies a parameterless, topic-driven explanation rather than a lookup keyed on user input.

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 subject ('how the four Sunni schools differ on food') and adds reasoning/agreement detail, but it also claims to answer 'is it halal?' across food, cosmetics, medicines, stocks, funds, crypto and money products — a scope that overlaps almost every sibling (halalornot_check_crypto, check_fund, screen_stock, ask_is_it_halal). The result is a purpose that is stated but not cleanly distinguished from the rest of the family.

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 explicit statement of when to choose this tool over ask_is_it_halal, explain_ingredient, or the check_* siblings. Given the heavy overlap in the broad 'answers is it halal' claim, the absence of any routing or exclusion guidance leaves the agent guessing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds output context (Asr times plus suhoor/iftar) but then fills the rest with irrelevant halal-checking claims that add no behavioral value for a prayer-times tool.

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 is front-loaded in the first sentence, but the description is then padded with a long block of unrelated halal-ruling content (food, cosmetics, medicines, schools, reasoning, alternatives) that does not earn its place and appears to be boilerplate from a sibling tool.

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

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

For a read-only, no-required-param tool with full schema coverage and no output schema, the description supplies reasonable output context (Asr times, suhoor/iftar). But the contamination by off-topic copy and absence of any when-to-use guidance leaves it only minimally adequate.

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

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

Schema description coverage is 100%, so the schema already documents lat, lon, city, date and method, including the enum values. The description adds no parameter meaning beyond that, which is the baseline 3 when the schema does the heavy lifting.

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

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

The opening sentence gives a concrete verb+resource: today's prayer times for a place, including Asr times and Ramadan suhoor/iftar. However, the remainder of the description abruptly pivots to generic 'is it halal?' copy about food, cosmetics, stocks and crypto, which describes a different tool and muddies what this one actually does.

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

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

There is no statement of when to use this tool versus alternatives such as halalornot_ask_is_it_halal or halalornot_explain_schools, nor any mention of prerequisites for lat/lon vs city. Usage must be inferred entirely from the title.

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, openWorldHint=false and destructiveHint=false, so safety and determinism are covered. The description adds useful domain context — scholarly agreement/dissent plus reasoning and halal alternatives — but the trailing truncation ('halal alt...') cuts off a stated behavioral trait.

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?

It is short, but it is a single run-on enumeration that ends mid-word ('halal alt...'), so the description is truncated rather than concise — the closing promise of the tool is literally missing.

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 no-param, read-only listing tool with no output schema, the description should at minimum say what the returned rulebook contains or how it is structured. It gestures at that ('showing where the four Sunni schools... agree and where they differ') but the truncation leaves the return content underspecified.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly does not pretend any inputs 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 conveys the coverage domain (food, cosmetics, medicines, stocks, funds, crypto, money, everyday life) and the comparative angle across the four Sunni schools, but it never states the actual operation — that this tool returns a list of rules — and reads much like an answering tool, blurring it with halalornot_ask_is_it_halal and halalornot_list_topics.

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 guidance at all: nothing says to pick this over ask_is_it_halal (for verdicts), list_topics (for topic discovery) or explain_schools (for madhhab comparison), even though all four sit in the same family.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that results show where the four Sunni schools and main scholarly bodies agree and differ, with reasoning and alternatives, which is useful content context. It stops short of describing result format or pagination, which is a minor gap given a read-only list tool.

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 opening two fragments ('Halal or Not. Every question the rulebook covers.') simply repeat the tool name and title before any operative content, which is wasteful front-loading. The remainder is a single long sentence that packs scope detail but is truncated, so the structure is adequate rather than efficient.

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

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

For a read-only list tool with one optional, fully documented enum parameter and no output schema, the minimum bar is met: the scope of covered subject areas is stated. However, the absence of any usage guidance relative to the many halalornot siblings leaves an agent without enough to reliably choose this tool over halalornot_list_rules or the specific check tools.

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 a single optional enum parameter (money, crypto, medicine, food, life), so the schema already carries the parameter semantics. The description references the same domains (food, cosmetics, medicines, stocks, funds, crypto, money products, everyday life) but adds no syntax or filtering detail beyond what the schema states. 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 conveys that this tool surfaces the topics/questions the rulebook covers (food, cosmetics, medicines, money, crypto, life), which aligns with a list operation, but it phrases the purpose as answering 'is it halal?' rather than enumerating topics. It does not distinguish itself from close siblings like halalornot_list_rules or halalornot_ask_is_it_halal, leaving the agent to infer which list is which.

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 guidance and no mention of alternatives. With siblings such as halalornot_list_rules and halalornot_ask_is_it_halal in scope, the description never explains when to enumerate topics versus query a specific item or fetch the rule list, so selection is left entirely 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 declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower, yet the description adds real behavior: the ordered sequence of screens applied and the fact that results link to halal alternatives. It does not disclose response format or timing, but the added process detail is substantive.

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 body is short and dense with real information, but the leading 'Halal or Not. Is this stock halal?.' duplicates the title verbatim and pushes the actual substance to the third sentence. Two of five fragments do not earn their place.

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

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

No output schema exists, and the description compensates by indicating the result is a per-standard screening plus links to halal alternatives. For a one-parameter, read-only tool that is nearly complete; only the precise verdict shape remains unstated.

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, but the description extends the single parameter beyond the schema's 'US stock ticker' by noting a company name also works with concrete examples (nvidia, philip morris). That is genuine added meaning about accepted input formats.

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 ('Screens a US-listed stock') plus the methodology (business screen, then AAOIFI/Dow Jones/S&P/MSCI debt screens), which separates it from siblings like halalornot_check_crypto or check_fund. The opening two fragments merely restate the title, and it never explicitly contrasts with mizan_screen_company or halalornot_ask_is_it_halal, so it stops short of 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?

'A company name also works (nvidia, philip morris)' gives useful input guidance, and the mention of links to halal alternatives hints at follow-up flow. But there is no statement of when to pick this over the sibling screeners (mizan_screen_company, halalornot_ask_is_it_halal) or any exclusion, 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 cover the safety profile (readOnly, idempotent, non-destructive). The description adds real behavioral value beyond that: it discloses the result shape (up to five matches, each with a verdict, plus a 'say' line for the best match) and explains the brand_statement override rule with a concrete example.

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 purpose first, then return behavior and the brand_statement rule. The opening 'Halal or Not. Find products by name and check them.' partially restates the title, but the remaining sentences each add substantive 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?

With no output schema, the description appropriately explains the return values (verdicts, 'say' line, brand_statement). It covers purpose, scope, and output well, though it omits any statement about when to prefer the barcode-specific sibling.

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 both parameters are already documented in the schema. The description adds only the 'Haribo Starmix' example of a name query and no country-format detail, so it stays at the baseline for a fully-covered 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: searches Open Food Facts by name or brand and returns up to five matches. It is clearly a search/lookup tool, but it does not explicitly differentiate itself from the sibling halalornot_check_product_by_barcode, and the q parameter even accepts barcodes, leaving the boundary slightly ambiguous.

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 by 'Find products by name and check them' and the search behavior. There is no explicit when-to-use guidance, no exclusions, and no reference to alternatives such as check_product_by_barcode or ask_is_it_halal.

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). The description adds real behavioral context beyond them: ids remain valid later because they carry what is needed, and NHS Jobs/Teaching Vacancies results surface the closing date. These are useful traits not derivable from 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 purpose followed by usage examples and the key id constraint; every sentence carries information. The opening 'Job Spotter. Details for one job...' mildly duplicates the title, costing some tightness but little else.

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

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

With no output schema, the description still names a concrete returned field (closing date for NHS Jobs/Teaching Vacancies) and explains id durability, covering what an agent needs to call and reuse it. It could go further on the shape of a job-detail response, but the essentials are 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by stressing that the id must be copied exactly as given and that it encodes sufficient state to keep working later. That reinforces correct invocation rather than merely restating the field.

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 (retrieve details for one job) and scopes it to a job that came from a prior search result, which cleanly separates it from jobspotter_search_jobs. An agent can tell what this returns 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?

Gives explicit triggering conditions with concrete user-phrasing examples ('tell me more about the second one', 'what's the apply link for the Uber job'), which is strong context. It doesn't explicitly name the sibling search tool or state when-not to use this, so it stops short of the top tier.

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 behavioral context: the upstream sources (Remotive, Himalayas, Jobicy, Remote OK), the attribution obligation, and the note that `say` handles crediting automatically.

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 purpose before the examples, and each sentence is largely functional. The redundant 'Job Spotter.' opener and five near-identical example queries add some length that could be trimmed without loss.

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

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

No output schema exists, yet the description says only that it returns listings from named sources and covers the natural-language input model well. It stops short of describing the return shape (fields, ordering), but for a search tool with a full schema and rich annotations this is close to complete.

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