Vedaword

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

Annotations already declare readOnlyHint and closed-world, so safety is covered; the description goes further by disclosing the reply contract (`next` carries the arguments for the continuation call) and the language behavior (not a filter, results report their actual language). It also routes verse quoting to get_verse via `unit_id`, which is behavior an agent could not infer from 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?

Front-loaded with purpose, then the when-to-use clause, then the three-step procedure, then the handoff to get_verse. Every sentence carries distinct information; no filler or restatement of the name.

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?

Eight parameters and no output schema would normally be a gap, but the description supplies the missing return-value contract (`next`, labels and translations, paging) and the stepwise invocation model. An agent can drive the full browse sequence from this text alone.

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 each parameter is already documented; the description adds the compositional semantics the schema lacks — which parameters belong to which of the three steps and that `chapter` must be the `index` from the previous listing. It does not restate pagination semantics, but the schema handles those adequately.

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 ("Walk a work's structure in order") and immediately concretizes the hierarchy: work -> sections -> chapters -> verses. It also explicitly contrasts itself with search_texts, so an agent can choose between browsing and searching 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 concrete triggering situations (reading a chapter or book through, asking what follows a verse, asking what a book contains) and names the alternative that cannot serve them ("search_texts cannot do that"). It also prescribes exact escalation: `work` alone, then `section`, then `chapter` with the `index`.

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

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

Annotations cover safety (readOnlyHint) and scope (openWorldHint=false), and the description adds behavioral context they don't: matching is semantic rather than lexical, an empty result is a legitimate answer meaning the library attests the idea once, and same-chapter neighbors are near-duplicates that 'prove nothing.' That last point prevents a real false-positive pattern an agent would otherwise fall into.

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 paragraphs ordered by importance: what it does and its sibling boundary first, use cases and the key parameter second, the empty-result caveat last. No sentence restates the name or the schema.

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 return-value burden and does handle the most important cases: that results report their actual language and that zero results is meaningful. It stops short of saying what a result actually contains (citation, work, verse text, similarity measure), which is the one gap for an agent consuming the 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 coverage is 100%, so the baseline is 3; the description earns above that by explaining the intent behind exclude_same_work — independent corroboration versus repetition — and warning that the adjacent verse is trivially similar. It does not add anything for limit or verse beyond what the schema already documents.

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 passages similar to a given verse) plus the mechanism that defines it: similarity by meaning, not by shared words. It explicitly contrasts itself with the sibling search_texts, so an agent can choose between them 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 an explicit routing rule — 'Start here when you already have a verse; when you only have words, a question or a term, use search_texts' — naming the alternative and the condition that selects it. It also lists three concrete use cases (verify a teaching, gather parallels, compare treatments of a subject).

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 a safe read-only, closed-world operation, and the description adds meaningful domain behavior: the fast day depends on the tithi at local sunrise, the fast-breaking window is minutes-wide and city-specific, and each observance links to a story/verse page. It does not describe response format or pagination details, but it adds substantial context beyond the annotations.

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

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

Two short paragraphs with no wasted text. The primary purpose and the critical location constraint are front-loaded, and each sentence contributes either routing guidance or essential behavioral context.

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 six-parameter read-only calendar tool with no output schema, the description covers purpose, when to use it, location requirements, and the nature of returned links. It does not mention the days or language parameters, but those are fully documented in the schema and are secondary to correct invocation.

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. The description goes beyond the schema by explaining why latitude, longitude, and timezone are required and consequential—local sunrise determines the fast day and the break-fast time differs by city—which helps the agent avoid guessing a location.

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 (Ekadashi fasts, festivals, acharya appearance/disappearance days) and a specific computation scope ('computed for one place'). It is immediately distinguishable from all listed siblings, which are text/verse browsing 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?

It gives clear triggering conditions: any question about when an Ekadashi or festival falls, or when to break a fast. It also advises asking the user for their location rather than guessing. It lacks explicit when-not-to-use guidance or named alternatives, but the sibling set makes overlap unlikely.

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 only cover readOnlyHint and openWorldHint, so the description carries the real disclosure burden and does well: it says citations may be written any way a person writes them, that `language` is a preference and not a filter (results report their actual language), and that each reply includes five verses either side with translations. It stops short of describing error behaviour for an unresolved citation or the exact shape/ordering of the returned payload.

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 what you get, then when to call it, then the alternatives, then the traversal recipe — a sensible information order with no filler sentences. It runs three paragraphs and the final traversal paragraph is dense, but every clause is actionable rather than decorative.

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 describe the return payload, and it does: the fields returned, the word-by-word table's purpose, and the neighbour verses included under `context`. Combined with the routing guidance and citation flexibility, an agent has everything needed to call 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 the baseline is 3; the description earns above that by adding semantics the schema doesn't: the `verse` parameter accepts human-written citations, not just internal ids, and `context` is the hook for the chained traversal recipe using the neighbour's `unit_id`. The `context` 0–5 bound and language enum remain schema-only, which is fine.

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?

Opens with a specific verb and resource ("Fetch one verse whole") and enumerates exactly what comes back: Devanāgarī, IAST, word-by-word breakdown, translation, commentary, optional neighbours. It explicitly distinguishes itself from search_texts (discovery) and browse_work (sequential reading), so an agent can route between the three 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?

States concrete triggers ("after search_texts when you are going to quote", "whenever the user names a verse") and names the alternative for the other case (browse_work for a chapter or whole book). It even documents a pagination recipe: re-call with context 5, then the unit_id of the last neighbour marked "after".

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?

The annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral context beyond that: results are grouped by period, include a short note, and include the books credited to each author. It does not mention pagination or the language fallback behavior, but with annotations present this is still a strong disclosure.

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

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

The description is front-loaded and only three sentences long, with no wasted framing. It does repeat the `era` enum values already present in the schema, which is mildly redundant, but it remains easy to scan.

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, but the description explains the shape of the result: authors grouped by period, each with a short note and credited books. Parameter behavior is fully covered by the schema, and annotations cover safety. Only minor details such as pagination or language behavior are left to the schema or 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 description coverage is 100%, so both parameters are already documented in the schema. The description adds a little context by calling out `era` as a filter and repeating its allowed values, but it does not mention the `language` parameter at all. With the schema doing the heavy lifting, 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 verb and resource: listing authors the tradition names, grouped by period, with notes and credited books. It also explicitly distinguishes the tool from list_works by saying to pass an author's `id` to list_works to see books. An agent can identify the tool's scope and sibling relationship 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?

It states exactly when to call it: when the user asks who wrote something or wants the works of one acharya. It also gives the alternative route for book-level results: pass the author's `id` to list_works. The usage boundary is clear and actionable.

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

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

Annotations cover read-only safety, but the description adds behavior they don't: the default response is deliberately terse ('no descriptions'), descriptions are opt-in, and several works exist only in Russian. Flagging a partial-coverage data caveat the agent would otherwise over-promise on is exactly the kind of disclosure annotations can't carry.

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 paragraphs, front-loaded with what you get and when to call it, then narrowing options, then the caveat. The shruti/smriti parenthetical is dense but load-bearing; no sentence is pure padding, though the response-shape sentence overlaps slightly with what the schema implies.

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, but the description names the returned fields and the default truncation, so the agent knows what it will receive. With four optional params and clear general shape, nothing needed to call it correctly or interpret results is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description earns an extra point by explaining relationships the schema doesn't encode — that `shruti` is the upanishad shelf and `smriti` spans itihasa plus purana, and that `author` takes an id from list_authors. It does restate the language-is-not-a-filter behavior already stated in the schema, which keeps it from a 5.

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

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

Specific verb + resource ('List the works') plus the exact payload (sizes, shelf, author, available languages). It also implicitly separates itself from verse-level siblings by mentioning 'work slugs for filtering', so an agent knows this is the catalog-level entry point.

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 conditions ('at the start of a conversation about scripture', 'when you need work slugs for filtering') and points to the sibling list_authors as the source of author ids. The closing caution to check `languages` before promising an English text is a real usage constraint, not filler.

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 and openWorldHint=false, so safety is covered. The description adds genuinely non-obvious provenance: the data comes from word-by-word breakdowns of ~30,000 verses and reflects translator-assigned meanings rather than dictionary glosses — a critical caveat that shapes how results should be interpreted. It stops short of describing result ordering or limits beyond the examples cap.

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 paragraphs: the first front-loads the return payload, the second supplies the corpus-provenance caveat and usage triggers. No sentence is filler; each adds either scope or behavioral context.

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 compensates by naming the four result components (spellings, meanings, gloss counts, examples), and it explains the data's origin so an agent knows what to trust. Nothing needed to invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, including script/IAST guidance, the examples default of 5, and the non-filter nature of the language enum, so the schema already carries parameter meaning. The description adds no parameter-level detail beyond framing the term concept, which is the correct baseline when the schema does the work.

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 (look up) and resource (Sanskrit word) and enumerates exactly what is returned: cross-script spellings, corpus meanings, verse gloss counts, and occurrence examples. It also draws a sharp boundary against a lexicon ('not a lexicon's list of everything it could mean'), so an agent can distinguish this from generic search or its own translation attempt.

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 clear positive triggers: 'Use it before translating a term yourself, and whenever the user asks what a word means.' That is actionable context lacking in most definitions, but it never names a sibling alternative (e.g., search_texts for non-Sanskrit scripts) inside the description, so exclusion guidance is left to the schema.

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 read-only and closed-world safety, yet the description adds substantial behavior beyond them: what a result contains (exact citation, URL, version hash), the confidence contract including the critical 'none' = no answer / empty list instruction, and how matched_by='vector' implies zero lexical overlap. This is exactly the guidance an agent needs to interpret results honestly.

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 what the tool is and why it works, then a usage section, then return-value semantics. Each paragraph carries distinct, non-redundant information; nothing is 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, and the description compensates by naming the returned fields, the confidence levels, and the interpretation rule for matched_by. Combined with the sibling routing, an agent has everything needed to call it and to use the results 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; the description still adds value by explaining the hybrid meaning+wording search behind `query` and cross-script term matching, which the schema does not say. It does not elaborate on limit or full_text beyond the schema, so it stays a notch above baseline rather than fully additive.

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 ('Search the Vedaword library of Sanskrit scripture') and immediately names the two retrieval modes (meaning and wording). It explicitly differentiates itself from find_similar_verses, get_verse, and browse_work, so an agent can pick it 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 an explicit trigger ('Start here when you have words: a question, a phrase, a term') plus a complete routing table of alternatives and the condition each covers (known verse to read whole → get_verse, chapter in order → browse_work). Also states the excluded case explicitly.

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