Scroll the Gurbani

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description usefully adds the shape of each returned line (Gurmukhi + transliteration + English), which is real information beyond the annotations. It says nothing about response size across the 1–1430 range or pagination, leaving the main behavioral unknown unaddressed.

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 duplicates the tool title verbatim, so it spends space restating structured metadata. The second sentence is a sprawling semicolon-joined list of unrelated app features (daily shabad, plans, search, books) that does not earn its place in this tool's definition and actively dilutes the front-loaded signal.

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 carry return-value information, and it does name the three content streams per line. However, for a getter spanning 1430 pages it omits any notion of volume, pagination, or error behavior when 'ang' is out of range, so the picture is only partially 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%: the single 'ang' parameter carries its own description and 1–1430 bounds, so the schema does the heavy lifting. The description adds no format or edge-case detail beyond that, which is the expected baseline 3 when the schema is complete for a one-parameter tool.

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 states a concrete verb-less but unambiguous action: retrieving 'every line on an Ang' with the three content forms (Gurmukhi, transliteration, English). That is a specific resource with clear scope. It does not, however, contrast itself with siblings like get_shabad or get_reading, and the trailing sentence 'Gurbani: daily shabad, plans, search, Ang and shabad lookup; whole books from the Library' is an app-wide feature list rather than a statement of what this 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?

No sentence tells the agent when to pick get_ang over get_shabad, get_reading, get_card, or read_book. The second sentence name-drops 'shabad', 'search' and 'Library' without tying them to any decision condition, so it reads as broad product context rather than routing guidance. An agent must guess from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description contributes one genuine behavioral fact — the output is 'one line at a time, for voice,' implying TTS-oriented plain text — but says nothing about pagination, how many lines exist, or what happens when n exceeds the reading length.

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 duplicates the title verbatim (including a stray double period), and the second sentence enumerates capabilities — 'daily shabad, plans, search, Ang and shabad lookup; whole books from the Library' — that belong to sibling tools, not this one, making the scope read as broader than it is.

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?

All three parameters are optional, there is no output schema, and the tool name is non-obvious, so the description carries the real burden of explaining what is returned. It never defines 'card', never explains how n, date, and reading interact, and the scope-listing second sentence actively muddies the picture.

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

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

Schema description coverage is 100%: n, date, and reading all carry descriptions with defaults, and the reading param already points at list_readings. The description adds no parameter semantics 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 verb/resource pair 'get_card' is opaque on its own, and the description only clarifies it by restating the title: 'Today's reading one line at a time, for voice.' That conveys the deliverable (one line of the day's reading, formatted for speech), but it never says what a 'card' is nor distinguishes this from siblings get_reading and 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?

There is no when-to-use guidance, no exclusions, and no reference to the alternatives. An agent choosing between get_card, get_reading, and get_today gets no signal about which to pick, and the trailing 'Gurbani: daily shabad, plans, search...' blurb describes the whole server's scope rather than this tool's.

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, and destructiveHint=false, so the safety profile is covered. The description adds a faint behavioral hint with 'line by line' and 'read a passage at a time,' suggesting chunked or paginated retrieval, but gives no details on pagination, error behavior, or response format.

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 and somewhat front-loaded with 'One reading or plan, line by line.' However, the second sentence is a run-on list of content domains that does not clearly earn its place and risks confusing rather than clarifying the tool's scope.

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

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

For a simple one-parameter read tool with rich annotations and no output schema, the description is minimally adequate. But it fails to distinguish this tool from sibling options like read_book and get_shabad, which could lead an agent to mis-select the tool despite the clear schema and safety annotations.

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

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

Schema description coverage is 100%, and the single id parameter is fully documented in the schema as coming from list_readings or being a plan name. The description adds no additional parameter semantics 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 'One reading or plan, line by line' signals the resource retrieved but lacks a clear verb and is blurred by the second sentence listing many content types (daily shabad, plans, search, Ang, shabad lookup, whole books). This overlap with siblings like get_shabad, get_ang, and read_book makes the tool's specific purpose vague.

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 offers no when-to-use or when-not-to-use guidance. It does not point to list_readings as the source of ids or explain how this tool differs from read_book, get_shabad, or get_ang, leaving the agent to guess based on the schema alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety and idempotency profile is fully covered structurally. The description adds only that the result includes transliteration and English, which is modest output-content context; it says nothing about error behavior for an invalid id 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 sentence is fine, but the second is an unfocused enumeration of unrelated features ('daily shabad, plans, search, Ang and shabad lookup; whole books') that consumes space without telling the agent anything about calling this tool. It is padding rather than concision.

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 does usefully signal that transliteration and English are returned, which is the one piece of return-value context the agent gets. However, it omits anything about the shape of the returned shabad (verses, lines, ordering) and the stray toolset enumeration dilutes rather than completes the picture.

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

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

Schema coverage is 100% and the single parameter 'id' is already documented as 'A BaniDB shabad ID.' The description's 'by BaniDB id' merely restates the schema and adds no format, range, or validity detail beyond it. Baseline 3 applies since the schema carries the 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 names the resource (a whole shabad) and its retrieval key (BaniDB id) plus the output content, so the core purpose is discernible, but it is phrased as a title-like noun clause rather than a verb+resource statement. It does nothing to distinguish this tool from siblings such as get_ang or 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?

There is no guidance on when to use this tool versus get_ang, get_reading, or search_readings. The trailing clause ('daily shabad, plans, search, Ang and shabad lookup; whole books from the Library') reads as a catalog of the entire toolset and could actively mislead an agent into thinking this tool also serves search, Ang, or book-reading requests.

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=true, so the safety and repeatability profile is fully covered. The description adds only the point that output mirrors what the app shows today, and says nothing about pagination, output shape, or how a past date behaves.

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 definition is short, which is good, but the second sentence is copy-paste boilerplate listing features this tool does not cover and therefore does not earn its place. The useful scoping statement is front-loaded, which is the main structural strength.

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-optional-parameter read tool with full schema coverage and annotations covering safety, the definition is minimally adequate. It is missing usage context (when this beats get_reading/get_card) and the catalog-style second sentence adds noise instead of completing the picture.

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

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

Schema description coverage is 100%: the single optional date parameter is documented as YYYY-MM-DD defaulting to today (UTC). The description adds no further meaning about the parameter, 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 states a specific resource ('Today's reading, line by line') and grounds it against the app's rendering, which is clear. However, the second sentence is a generic app-wide blurb listing unrelated features (plans, search, Ang, Library books) that muddies rather than sharpens the purpose, and no sibling such as get_reading or list_readings is named for 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?

There is no explicit when-to-use guidance, no when-not-to-use condition, and no alternative tool named. The only implicit signal is that the optional date defaults to today, which hints at the scope but does not tell an agent when to prefer this over get_reading or get_card.

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 and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds no behavioral context beyond that – no mention of pagination, catalog scope, result ordering, or what 'the Library' means operationally. It only restates domain framing.

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, then appends a run-on clause listing unrelated Gurbani capabilities that do not belong to a book-listing tool. Substantial content is wasted rather than front-loading a clean statement of what the tool returns.

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 listing with rich annotations, the description is minimally adequate but not complete. It doesn't say what the listing returns or how to act on it, and the extra Gurbani clause muddies rather than fills the 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?

The tool takes zero parameters, so there is no parameter semantics for the description to clarify. Baseline of 4 applies; the description neither adds nor detracts from parameter understanding.

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

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

The first sentence names the resource (whole books in the Library that can be read a passage at a time), so an agent can infer this lists available books. However the verb 'list' is never stated, and the second sentence mixes in unrelated Gurbani features (daily shabad, plans, search, Ang and shabad lookup) that don't describe this tool. It also fails to distinguish itself from siblings read_book or list_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?

There is no indication of when to call this tool versus the many siblings (list_readings, read_book, get_reading). The description offers no trigger condition, prerequisite, or exclusion, leaving the agent to guess from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds no behavioral context of its own for this tool (no mention of pagination, ordering, or scope) and instead describes other tools' behaviors, such as reading a whole book 'a passage at a time'.

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 sentence duplicates the title, and the second sentence is a sprawling semicolon list of sibling capabilities that is off-topic for this tool. The content that would matter (what this tool returns, how it differs from the siblings) is absent, so the text is both redundant and misdirected.

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, zero-parameter list tool with no output schema, the annotations cover the safety semantics, so little is strictly required. However, the description never states what list_readings actually returns, and its second sentence conflates this tool with its siblings, leaving the agent to guess its role in the suite.

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 surface for the description to clarify. Baseline 4 applies per the rubric for zero-parameter tools.

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

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

The first sentence names the resource ('All curated daily readings and plans') but never states the list/retrieve action, and it is nearly a verbatim restatement of the title. The second sentence is a catalog of sibling-tool functionality (daily shabad, search, Ang/shabad lookup, whole books) rather than a description of what list_readings itself does, so the agent cannot cleanly distinguish this tool from get_reading, get_today, or list_books.

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 enumerates what sibling tools cover ('daily shabad, plans, search, Ang and shabad lookup; whole books from the Library') but never says when to choose list_readings over those siblings. There are no conditions, prerequisites, or exclusions to guide selection.

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, and destructiveHint=false, covering the safety profile. The description adds that reading proceeds passage-by-passage and carries into the next chapter, which is useful sequential-reading context, but no additional details on auth, rate limits, or return format.

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 essentially a restatement of the title and is unclear. The second sentence is a run-on list mixing unrelated features ('daily shabad, plans, search, Ang and shabad lookup') with the actual book-reading capability, hurting front-loading and focus.

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 explain what a reading returns, but it only says it reads a passage at a time. Annotations cover safety and schema covers parameters, so it is minimally complete but lacks return-format details for a read tool.

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

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

Schema description coverage is 100%, so the schema already fully documents all four parameters. The description adds no parameter-specific meaning beyond what the schema provides, making the baseline score of 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?

The description states the resource (whole books, a passage at a time) but the first sentence about 'Follow next' is a confusing UI instruction rather than a clear statement of what the tool does. It does not distinguish this tool from siblings like get_reading or 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?

No explicit when-to-use guidance or alternatives are mentioned. The phrase 'Follow next for the next passage' is an in-tool navigation hint, not a condition for selecting this tool over siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered elsewhere. The description does add one genuinely useful behavioral fact — results are relevance-ranked with the best match first — but says nothing about result limits, pagination, or what a match 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?

The ranking constraint is front-loaded well in the first sentence, but the second sentence is a grab-bag of functionality that reads as scope-creep and does not clearly earn its place in a one-parameter search 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 single-required-parameter read-only search with no output schema, the definition is minimally viable: purpose, ranking, and safety are all inferable. It still leaves the agent guessing about result volume and how this differs operationally from list_readings and read_book.

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 explains q as 'Words or a bani's name to search for, for example Japji or humility.' The description adds no query syntax, matching mode, or format guidance 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?

The first sentence gives a clear verb+resource (search curated readings) plus the ranking behavior ('best match first'), which distinguishes it from the lookup siblings. However, the second sentence lists 'daily shabad, plans, search, Ang and shabad lookup' — functions that appear to belong to siblings like get_today, get_ang, and get_shabad — which blurs rather than sharpens the tool's 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 statement relative to the nine siblings. Mentioning 'Ang and shabad lookup' without naming get_ang/get_shabad risks pointing the agent at the wrong tool rather than routing it correctly.

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