masnavi

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

Describes the return format in detail: structured entries with source, author, language, body markdown, and confidence levels. No annotations to contradict.

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?

Concise and front-loaded; every sentence adds value without 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?

Complete for a simple tool; explains return structure and confidence levels. Minor gap: does not mention if commentary may be unavailable for some beyts.

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?

Only one parameter (citation) with 100% schema coverage. Description does not add extra semantics beyond the schema examples.

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?

Clearly states the tool retrieves commentary for a specific Masnavi beyt, distinguishing it from sibling tools like lookup and 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 tells the agent when to use this tool: when a user asks 'what does this beyt mean' or queries a scholar's commentary on a specific beyt.

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?

With no annotations, the description discloses that the tool searches titles only, returns matches with first_citation and last_citation, and clarifies the global index pitfall. It could mention pagination or ordering but covers the main behavioral traits.

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 concise (4 sentences), front-loaded with purpose, and every sentence adds value. No 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?

Given the tool complexity (3 params, output schema exists), the description covers purpose, usage, parameter meaning, and output type. It also explains how to chain with get_range, making it complete for an agent.

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 low (33%), but the description explains the 'query' parameter (Persian phrase), gives an example, and clarifies 'daftar' as filtering. The 'limit' parameter is not explained but has schema constraints. The description adds 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?

The description clearly states the tool searches section titles for a Persian phrase, differentiating it from search (which likely searches beyt content) and get_range (for reading whole sections). The example solidifies the purpose.

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 tells when to use get_range instead (for multi-section stories) and warns against constructing a citation from first_beyt_global, providing clear when-not 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?

Despite no annotations, the description discloses max range (500 beyts), inclusive endpoints, and grouping by section. It does not explicitly state it is read-only, but that is implied for a fetch operation. The description adequately covers behavioral traits.

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 concise and front-loaded with the primary purpose. Four sentences each serve distinct purposes, with no superfluous 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?

Given the tool has 4 optional parameters and an output schema exists, the description covers input formats, constraints, use cases, and expected output structure (grouped by section). It is complete for the tool's complexity.

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 50% with descriptions for start and end. The description adds value by explaining the two modes (canonical citations vs. global indices) and the max range. It compensates for the missing schema descriptions of start_global and end_global.

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 it fetches ALL beyts between two endpoints inclusive, grouped by section. It distinguishes from siblings by explicitly advising against using get_section or lookup for this purpose.

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 explicitly states when to use (full story, long passage, sequence spanning multiple sections) and what not to use (many calls to get_section/lookup). This provides clear guidance to the agent.

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?

No annotations are provided, and the description only states a read operation without mentioning any behavioral traits such as authentication, rate limits, error handling, or what happens if the section is not found.

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 a single sentence, which is concise but lacks structure. It could benefit from front-loading key aspects like how to identify the section or what beyts are. Every word earns its place, but more detail is needed.

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?

Given the tool has 2 parameters and an output schema, the description is too minimal. It does not explain how to specify a section (slug vs ID) or what constitutes a 'full section'. With 8 sibling tools, more context is needed for correct usage.

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 description does not add meaning beyond the input schema. The schema has two nullable parameters (slug, section_id) with only slug having a description. The description does not explain how to use them (e.g., are they interchangeable? mutually exclusive?).

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 retrieves a full section with all its beyts, specifying both the action and resource. It distinguishes from siblings like find_sections (which likely finds/filters sections) and get_range (which might get a range).

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 guidance on when to use this tool versus alternatives like find_sections, get_range, or lookup. The description does not provide any context about preferred scenarios or conditions.

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?

With no annotations, the description must cover behavioral traits. It discloses that the tool fetches beyts by multiple identifier types and can include context via before/after parameters. However, it does not mention error handling, idempotency, or behavior when multiple identifiers are provided simultaneously, which limits transparency.

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, each serving a distinct purpose: the first defines core functionality, the second adds an optional feature. No redundant or irrelevant 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?

Given the tool has 6 parameters and an output schema, the description covers the primary functionality well. It explains how to identify a beyt and request context. However, it does not address potential conflicts when multiple identifiers are provided or the behavior when no identifier is given (though all parameters are optional). The existence of an output schema partially mitigates the need to describe return values.

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 description adds significant meaning beyond the schema by explaining the three lookup modes and providing an example for citations. Schema coverage is only 17%, so the description compensates by clarifying the purpose of daftar, beyt_in_daftar, beyt_global, and citation. However, 'after' and 'before' are only vaguely described as 'surrounding beyts' without detail.

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 verb 'Fetch' and the resource 'beyt', and specifies three distinct lookup methods (citation, daftar+beyt number, global index). This distinguishes it from sibling tools like 'search' or 'random_beyt'.

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 provides context that the tool is for fetching a specific beyt by known identifiers and optionally including surrounding beyts. However, it does not explicitly state when to use this vs. alternatives like 'search' for broader queries, nor does it mention any prerequisites or exclusions.

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?

With no annotations, the description should disclose that the operation is read-only and non-destructive. It only states the return behavior without discussing side effects, randomness guarantees, or performance characteristics.

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 a single sentence that immediately conveys the core functionality with no superfluous words, achieving high efficiency.

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?

Given the simple one-parameter interface, the description is adequate but could benefit from defining domain terms ('beyt', 'daftar') to fully inform an AI agent unfamiliar with the context.

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 description adds meaning to the 'daftar' parameter by stating it restricts selection, which goes beyond the schema's integer type. However, it does not define 'daftar' itself, leaving some ambiguity.

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 uses a specific verb 'return' and resource 'beyt', and clarifies optional restriction to 'daftar', which distinguishes it from sibling tools like 'search' or 'get_section' that have different purposes.

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 for random selection but does not provide explicit guidance on when to use versus alternatives, nor does it mention prerequisites or exclusions.

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?

No annotations are provided, so the description carries full burden. It states returns beyts with query terms ranked by relevance, implying read-only operation. No side effects or additional behaviors are disclosed.

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

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

Two sentences, front-loaded with main function, no wasted words. Efficient and clear.

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 description is basic; it does not mention pagination, sorting, or filtering by daftar. While an output schema likely covers return structure, additional context on parameters would improve completeness.

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 50%; the description adds no meaning beyond what the schema already provides for query and daftar. It does not explain limit and offset parameters, which are missing schema descriptions.

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 it performs full-text search across the Masnavi, returning matching beyts ranked by relevance. It distinguishes from sibling tools like 'explain' or 'lookup'.

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 notes it is useful for finding where a theme, word, or phrase appears, providing clear context. It does not explicitly state when not to use, but the use case is well defined.

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?

No annotations provided. The description mentions returning data but does not explicitly state that the tool is read-only or describe any side effects. It implies a safe browse operation but could be more transparent.

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 a single sentence with no extraneous information. It is concise and front-loaded with the core action.

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?

Given a simple tool with one optional parameter and an output schema present, the description is largely complete. It briefly describes the return values (titles, beyt counts, ranges). Could mention that null returns all daftars but not critical.

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 0%. The description mentions 'per daftar' but does not explain that the daftar parameter filters by book number or that null defaults to all daftars. The schema includes constraints (1-6) but the description adds minimal 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 clearly states the tool browses the Masnavi's section list and returns titled sections per daftar with beyt counts and ranges. It distinguishes from siblings like 'get_section' which likely retrieves a single section.

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 guidance on when to use this tool versus alternatives like 'get_section' or 'find_sections'. The purpose implies browsing but lacks direct comparison.

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?

No annotations are provided, so the description carries the burden. It discloses the three return statuses ('exact', 'fuzzy', 'not_found') and mentions citation and candidates. But it lacks details on side effects, permissions, or behavior with invalid inputs.

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 two sentences with no fluff. The first sentence states the core purpose, and the second provides usage guidance. Every 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?

Given that an output schema exists (though not shown), the description adequately explains the key return statuses. It is complete enough for a verification tool, though it could briefly mention the output 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 50%; the text parameter is described in both schema and tool description, but fuzzy_threshold lacks any explanation in either. The tool description does not add meaning beyond what the schema already provides for the parameters.

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 verb 'check' and the resource 'candidate quote attributed to Rumi's Masnavi'. It distinguishes from siblings like search or lookup by specifying it is for verification to avoid hallucination.

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 explicitly says 'USE THIS BEFORE QUOTING RUMI to avoid hallucination', providing clear when-to-use context. However, it does not explicitly state when not to use or mention alternatives among siblings.

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