Gita & Mahabharata

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world). The description adds genuinely non-obvious behavioral context beyond that: the verse is globally shared per day and keyed to India time, which an agent could not infer from the schema. It does not describe the return shape, but no output schema exists to cover that either.

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

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

Two tight sentences with no filler; the usage trigger is front-loaded. The timezone qualifier is slightly buried at the end but it is short and earns its place.

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

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

For a no-parameter, read-only lookup with no output schema, the description covers what the agent needs to select and call it. The only mild gap is the absence of any hint about the response content, which the missing output schema would otherwise supply.

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 clarify and the baseline of 4 applies. Schema coverage is 100% trivially.

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 (the Bhagavad Gita daily verse) with a clear retrieval verb and scope. The 'today's verse' framing distinguishes it from sibling get_gita_verse (a specific verse) and search_gita (a search).

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

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

Explicitly names the triggering conditions ('today's verse', 'a daily verse', 'a random verse'), which is strong when-to-use guidance. It does not explicitly name the alternatives (e.g., use get_gita_verse for a specific chapter/verse), so it stops short of a full routing statement.

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, covering the safety profile. The description adds only the special case that chapter 0 returns the chapter list, which is more parameter guidance than behavioral disclosure; no rate limits, output shape, or side effects are discussed.

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

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

One compact sentence front-loads the trigger and includes the special 0 argument; every clause is useful and 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 simple one-parameter read-only tool with full schema coverage and strong annotations, the description supplies the purpose, trigger, and the special 0-case needed to call it correctly. No output schema exists, but the expected result ('summary'/'overview') is sufficiently implied.

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

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

Schema description coverage is 100% and the single parameter's description already states '1-18, or 0 for all chapter names.' The description's '(pass chapter 0 for the list of all chapters)' reinforces this but does not add syntax, format, or meaning beyond the schema.

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

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

The description identifies the resource (Bhagavad Gita chapters) and the operation (summary/overview), and its chapter-level scope distinguishes it from verse-level siblings like get_gita_verse and search_gita. It stops short of explicitly naming those siblings, so it is clear but not fully differentiated.

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

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

It states exactly when to use the tool—when the user asks what a chapter is about or wants an overview of all 18 chapters—and tells the agent to pass 0 for the chapter list. It gives no exclusions or alternative tools, so 4 rather than 5.

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

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

Annotations already declare the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs additive context. It supplies the return payload composition, which matters because no output schema exists. It does not mention the 10-verse range cap, which lives only in the schema.

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

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

Two sentences, zero filler, with the usage trigger front-loaded ahead of the return payload. Nothing here restates the title or wastes 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?

For a three-parameter lookup with no output schema, the description covers the trigger, the input convention, and the return contents, which is most of what an agent needs. The remaining gap is bounds/limits guidance that lives only in the schema's numeric constraints.

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

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

Schema coverage is only 33%: chapter and verse carry no descriptions, and only verse_end documents the max-10 range. The examples ('Gita 2.47') do clarify the chapter.verse convention and the x-y range convention, but the description never states the 1-18 chapter bound or the per-chapter verse bounds that the schema enforces.

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

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

The description names a specific verb (read/return) and resource (a named Bhagavad Gita verse or range) and specifies the payload: Sanskrit, IAST transliteration, and two translations. The condition 'use when the user names a specific verse' implicitly separates it from search_gita and daily_verse, though no sibling is named explicitly.

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

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

It states an explicit trigger condition with concrete input examples ('Gita 2.47', 'chapter 18 verses 65-66'), so an agent can recognize when this tool applies. There is no explicit when-not clause pointing to search_gita for fuzzy or thematic queries, which is the only gap.

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 genuinely useful behavioral fact not in the annotations, 'Long sections are paged,' but says nothing about how paging terminates, whether page is 1-indexed, or what a page contains. That is meaningful added context on top of annotations, but thin.

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, front-loaded with the verb and resource, followed by the routing cue. No filler, no restatement of the title.

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

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

There is no output schema, so the description should carry more of the burden. Paging is acknowledged but never resolved (how to know more pages exist, whether the response indicates total pages), and the required 'section' parameter is undocumented anywhere. Adequate for a simple read tool, but clearly incomplete.

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 only 33% — only 'parva' is documented, while the required 'section' (1-400) and 'page' carry no descriptions. The description's mention of paging gestures at the page parameter but never explains it, and it adds nothing about the section identifier. With low coverage the description was expected to compensate and does not.

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 ('Read the full text of one section of the Mahabharata') plus the translation used (Ganguli), and it explicitly frames itself against the sibling search_mahabharata as the retrieval counterpart to a search. An agent can distinguish this from search_mahabharata without opening either 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 a concrete triggering condition: use it 'after search_mahabharata returned a relevant passage.' That names the alternative and the workflow position. It stops short of an explicit when-not (e.g. don't use this for browsing or for the Gita siblings), so it is clear context rather than full 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 establish the safe, read-only, idempotent, closed-world profile, so the description is free to add value elsewhere and does: it discloses the exact return payload (Sanskrit, transliteration, two translations, chapter.verse) and an operational rule ("Always cite the reference"). It does not mention ranking, relevance cutoffs, or empty-result behavior, keeping it out of the 5 range.

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 trigger condition, then search mechanics, then query-format guidance, then the return contract. The parenthetical situation list is long but earns its place by widening recall; no sentence is filler.

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

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

With no output schema, the description must carry the return contract, and it does precisely (fields plus reference format). Combined with the trigger guidance and query-language rule, an agent has everything needed to invoke this 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, but the description genuinely adds semantics the schema lacks: the query should be written in English describing the feeling even when the user wrote Hindi or Hinglish, with worked examples. That materially changes how an agent formulates the required 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?

States a specific verb (semantic search) and resource (all 700 verses of the Bhagavad Gita), and the example queries plus the chapter.verse return make it unmistakable against siblings like get_gita_verse or search_mahabharata.

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?

Opens with an explicit trigger ("Use when the user asks for guidance, comfort, or a teaching on any life situation...") and enumerates the relevant situations, giving strong when-to-use guidance. It stops short of naming the sibling alternative (e.g. get_gita_verse for a specific known verse), so it misses the top of the range.

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 closed-world, so the safety profile is covered. The description adds genuinely useful context beyond that: it is a semantic (not keyword) search and it returns passages with parva and section references; it omits any note on result limits, though top_k's max of 6 is visible in the schema.

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

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

Three sentences, front-loaded with the usage trigger, then scope, then the optional filter and return shape. The long character parenthetical is helpful for retrieval matching but is the only place the text dilutes its density.

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 semantic search with no output schema, the description covers what the tool searches, how it filters, and the shape of the returned references. The remaining gap is result-set behavior (ordering, the top_k ceiling of 6), which is minor for this tool type.

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 only 33%, so the description should carry more weight. It clarifies the parva filter (book name or number 1-18) and implies query intent, but says nothing about top_k's role, default, or ceiling of 6, leaving one of three parameters unaddressed.

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 (semantic search) and resource (complete Mahabharata, Ganguli translation, all 18 parvas), and the topic triggers (stories, characters, events, dharma/ethics) make it easy to separate from search_gita or get_mahabharata_section 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?

"Use when the user asks about Mahabharata stories, characters..., events, or its teachings" gives a clear, quotable trigger condition. It does not, however, name alternatives or state when to prefer get_mahabharata_section or search_gita over this tool, so it falls short of a full when/when-not pairing.

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