masnavi

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

With no annotations provided, the description carries the full burden. It discloses the return format (beyt text plus structured commentary entries), the fields of each entry, and the confidence levels ('ai-draft' / 'reviewed' / 'verbatim'). It also notes the commentary is attributed to a primary source. This is valuable behavioral context, though it does not mention any side effects or error behavior.

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

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

The description is three sentences long, with the purpose stated first and no extraneous information. Every sentence adds value: purpose, output structure, and usage guidance.

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

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

The tool is simple with one parameter, no annotations, and no output schema. The description adequately explains the return values and usage. However, there is a slight ambiguity: the description says 'beyt of the Masnavi' but the schema includes 'g:7421' which may refer to a ghazal, and this is not reconciled. This minor gap prevents a perfect score.

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

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

The input schema has 100% coverage for the single parameter 'citation', including examples like 'M1:1' and 'g:7421'. The description does not add additional meaning beyond the schema, so it meets the baseline of 3.

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

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

The description uses a specific verb ('Get commentary') with a clear resource ('specific beyt of the Masnavi'), and distinguishes itself by mentioning the output structure (commentary entries with source, author, language, etc.) and by giving usage examples. This clearly sets it apart from sibling tools like search 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 explicitly states when to use the tool: 'Use this when a user asks what does this beyt mean or what does <scholar> say about M1:1.' This gives clear trigger conditions, but it does not mention alternatives or when not to use it, so it falls short of a 5.

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

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

With no annotations, the description fully discloses the two-phase matching algorithm (exact phrase/AND-of-tokens, then meaning fallback), the match='meaning' flag with cosine score, the need for verification, and the distinction between global and daftar-local indices. This is rich behavioral context beyond 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?

The description is dense yet well-organized: purpose first, then matching behavior, citation usage, and a concrete example. Every sentence provides actionable information without filler, and the front-loading of the main purpose aids quick comprehension.

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's complexity (two-tier matching, citation fields, global index pitfall) and the existence of an output schema, the description is impressively complete. It covers edge cases, verification, and cross-references get_range and get_section, making it self-sufficient for 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 only 33% (limit and daftar lack descriptions). The description compensates by thoroughly explaining query semantics (exact phrase, AND-of-tokens, meaning fallback) and showing daftar=2 in the example. However, limit is never addressed, though its schema defaults and bounds mitigate 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 begins with 'Find sections (stories) by TITLE', a specific verb+resource statement that clearly states the tool's core function. It differentiates from siblings by detailing exact-word matching first and meaning fallback, and includes a concrete example, making the purpose unambiguous.

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

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

Explicit guidance is provided: use get_range with the first match's first_citation and last match's last_citation to read a full multi-section story, and verify meaning matches with get_section. It also warns against constructing citations from first_beyt_global, offering clear when-to and when-not-to instructions.

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 description discloses that it returns 'every beyt plus prev/next ghazal numbers', giving insight into output structure. It also exemplifies with a famous opening line. However, it does not address edge cases like missing or conflicting parameters, but overall provides useful behavioral context.

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

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

Two sentences with no wasted words; the first states purpose and the second provides an illustrative example. The content is front-loaded and efficient.

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

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

The description is sufficient for a simple fetch tool: it covers identification, output contents, and gives a concrete example. With an output schema present, the description doesn't need to enumerate fields.

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?

Both parameters are described in the schema, and the description enriches them by specifying the number range (1..3230) and exact citation patterns ('G1393' / 'G1393:2'). The example further clarifies usage.

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 fetches 'ONE complete ghazal of the Divan-e Shams' by number or citation, distinguishing it from siblings like get_range or get_section. It also provides a concrete citation format and a famous example.

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 use when you need a specific ghazal identified by its canonical number (1..3230) or a citation like 'G1393'. It doesn't explicitly compare with sibling tools, but the scoped purpose makes the use case clear.

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 key behavioral traits: endpoints are inclusive, results are grouped by section, and there's a hard maximum of 500 beyts. It also clarifies the two endpoint formats (canonical citations vs global indices), providing useful context beyond the bare 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?

Four sentences, each with a distinct purpose: action, usage guidance, endpoint format, and limit. No filler or repetition.

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 fetch tool with an output schema, the description covers the essential usage and constraints. It could mention error handling for exceeding the range, but the given info (grouping, inclusivity, max range) is sufficient for most agent calls. The sibling list context further clarifies its role.

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 descriptions cover start and end with examples, but start_global and end_global have no schema descriptions (50% coverage). The description partially compensates by naming them as 'global indices' and connecting them to the endpoint concept, but it doesn't disallow mixing endpoint types or specify parameter relationships (e.g., start must precede end). This leaves some semantic 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 opens with a precise action: 'Fetch ALL beyts between two endpoints, inclusive, grouped by section.' It distinguishes itself from siblings by explicitly positioning against get_section and lookup, making its unique scope clear.

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

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

Explicit guidance is given: 'Use this — NOT many calls to get_section or lookup — when a user asks for a full story, a long passage, or a sequence of beyts spanning multiple sections.' This states the when and the alternatives clearly.

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 does not disclose any behavioral traits such as error handling, authentication requirements, or the need to specify either slug or section_id. It only states the action.

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, concise sentence without filler words, front-loading the action 'Retrieve'.

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 presence of an output schema and the tool's moderate complexity, the description is too sparse. It does not clarify the relationship between the two parameters, nor does it provide enough distinguishing information relative to the 13 sibling tools, so the agent cannot reliably select and invoke it.

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 explain the two parameters or when to use slug versus section_id. While the schema describes slug as 'Stable URL slug', the description adds no additional meaning, leaving the optionality and selection ambiguous.

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 and resource ('Retrieve a full section') and clarifies it returns all beyts, distinguishing it from sibling tools like find_sections or get_ghazal by the scope of a 'full 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 guidance is provided on when to use this tool versus alternatives like get_range or find_sections. The description is solely a functional statement with no usage context.

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 carries the full behavioral burden. It discloses three lookup modes and the optional inclusion of surrounding beyts (before/after), which gives a clear picture of read-only behavior. However, it does not address parameter precedence or behavior when multiple identifiers are supplied.

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

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

The description is two sentences, front-loaded with the core action, and contains only informative details. No filler or repetition.

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?

While the description covers the main lookup modes and optional context, it omits critical guidance on required parameter selection (e.g., exactly one of citation, daftar+beyt, or beyt_global must be provided). The output schema covers return values, so that is not a gap, but the missing parameter-combination rules leave room for misuse.

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 17%, so the description must compensate. It explains citation format with an example, describes the daftar+beyt combination, the global beyt index, and mentions surrounding beyts for before/after. This maps well to the six parameters, though it does not explain precedence.

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 what the tool does: fetches a specific beyt using citation, daftar+beyt, or global index. The verb 'Fetch' plus the resource 'beyt' and the explicit identification modes distinguish it from sibling tools like get_range or get_ghazal.

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 retrieving a single known beyt, but does not explicitly state when to prefer this over alternatives such as get_range or search. It also does not mention that exactly one identifier should be supplied or what happens if multiple are provided.

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 provided, the description carries the full burden. It discloses the key behavior of randomness and the optional daftar filter, but does not explicitly state side effects (though 'Return' implies read-only) or any preconditions.

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, front-loaded sentence with no redundant words. It efficiently states the core function and the optional parameter.

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 covers the primary function and the optional parameter, and the output schema handles return details. It is slightly incomplete in not addressing edge cases or alternative uses, but is adequate for the tool's simplicity.

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 explains that the 'daftar' parameter optionally restricts the selection, adding functional meaning beyond the schema's type/range. However, it does not explain what a daftar represents or how the restriction works, 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 ('randomly-selected beyt'), clearly distinguishing this from sibling tools that perform lookups or searches. The optional daftar restriction further clarifies scope.

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 that this tool is for obtaining a random beyt, but it does not explicitly state when to prefer it over alternatives or when not to use it. No exclusions or alternative tool names are mentioned.

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 that it performs full-text search and ranks results by relevance, and scopes to the Masnavi. However, it does not mention read-only behavior, pagination, or any limitations, leaving significant gaps in behavioral 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 two sentences, front-loaded with purpose and behavior, and includes a useful use case. Every sentence earns its place, with no wasted words.

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 output schema exists, so return format is covered. The description explains what is searched and the type of results, but lacks guidance on choosing among sibling tools and doesn't mention pagination parameters. It is adequate for a simple search but has notable omissions in 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?

Schema description coverage is only 50% (query and daftar are described), but the description text adds no parameter details beyond the schema. It does not explain limit or offset semantics, which are undocumented in the schema, and does not compensate for this gap.

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 ('search') and resource ('Masnavi'), and states it returns beyts ranked by relevance. This clearly identifies the tool's function, though it does not explicitly distinguish it from sibling search tools like search_divan or search_meaning.

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 a clear use case ('finding where a theme, word, or phrase appears'), but offers no guidance on when to use this tool versus alternatives, and no exclusions are mentioned. The context is clear but incomplete for a tool with several similar 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?

With no annotations, the description must carry the behavioral disclosure burden. It explains the return format (divan citations like G1393:1) and the exact-match nature of the search. However, it does not explicitly state read-only behavior or address edge cases (e.g., no results, pagination), leaving a small gap in 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?

The description is three sentences, front-loaded with the core function, followed by return format and usage guidance. Every sentence earns its place, with no unnecessary details.

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 covers the tool's scope, return format, and usage guidance, and an output schema is present, reducing the need to explain return values. It lacks explicit pagination or limit details, but these are likely handled by the output schema or standard search expectations, leaving the description adequately complete.

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

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

Schema description coverage is only 33% (query has a description, limit and offset do not). The description adds 'exact Persian words' for query but provides no explanation or guidance for limit and offset, failing to compensate for the low schema coverage despite the need to do so.

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 performs full-text search across Rumi's ghazals (Divan-e Shams), distinct from the Masnavi, and explicitly returns beyts with divan citations. It differentiates from sibling tools by noting the alternative search_divan_meaning for theme-based 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?

The description explicitly provides a usage condition: 'Use when you know the exact Persian words' and recommends switching to search_divan_meaning for themes in any language. This clear guidance distinguishes the tool from its sibling and tells users exactly when to apply it.

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

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

With no annotations, the description fully discloses the core behavior: it searches both couplet-level and whole-ghazal vectors, meaning a matching ghazal can be found even without a matching couplet. It also reveals the status='unavailable' edge case and fallback. This goes well beyond a basic description.

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 four sentences, each contributing unique value: purpose, behavior detail, follow-up tool mention, and fallback. No fluff or repetition, and key information is front-loaded.

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's moderate complexity, the description covers purpose, usage context, behavioral nuance, return preview, status handling, and alternative tools. The presence of an output schema reduces the need to explain full return structure. This is a complete and self-sufficient description.

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% (query has description, limit does not). The description enriches the required query parameter by defining it as a theme, feeling, or idea in any language. It does not mention limit, but the schema already provides default/min/max constraints, making it self-explanatory. Overall, the core parameter semantics are well covered.

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 this is a semantic search over the Divan-e Shams ghazals, with a specific verb and resource. It differentiates from sibling search_divan by explicitly naming it as a fallback, and the return format (ghazals with couplet preview and cosine score) is concrete.

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 describes when to use it ('given a theme, feeling, or idea in ANY language') and provides an alternative ('fall back to search_divan') when the index is unavailable. This is direct usage guidance with an exclusion condition.

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 provided, the description carries full burden. It discloses that results include a cosine-similarity score and that a status field of 'unavailable' indicates the vector index is not built, with a fallback. It does not mention auth, rate limits, or ordering, but the key behavioral traits for a search tool are covered.

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 the core purpose, and the second sentence packs essential details (score, status, fallback) without redundancy. Every clause earns its place, making it precise and highly scannable.

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 covers the semantic nature, multi-language capability, a worked example, the similarity score field, the unavailable status, and the fallback to `search`. With an output schema present, return values need not be repeated. This is a complete yet concise description for a tool of this 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?

The schema already provides descriptions for `query` and `daftar`, covering 67% of parameters. The description reinforces the meaning-based semantic of `query` with an example, but adds no syntax or edge-case details. `limit` is self-explanatory. Given high schema coverage, baseline 3 is appropriate.

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

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

The description clearly states the tool performs semantic search ('find the beyts closest in MEANING'), specifies it works in ANY language, and provides a concrete example ('feeling separated from your origin' → M1:1). This distinguishes it from sibling tools like 'search' which presumably match exact words, making the purpose unmistakable.

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?

Explicit guidance is given on when to use this tool: 'when you have a theme, feeling, or idea rather than exact Persian words'. It also directly names an alternative and provides a fallback condition: if status='unavailable', fall back to `search`. This is clear, actionable, and differentiates from 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?

No annotations are provided, so the description carries the burden. It discloses the output format (titled sections per daftar with counts and ranges) but does not mention whether the operation is read-only, any pagination limits, or effects of omitting the daftar parameter. For a simple browse tool, this is adequate but lacks explicit safety context.

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

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

The description is two concise sentences, front-loaded with the action and resource, and contains no unnecessary words. Every phrase contributes to understanding the tool's purpose and output.

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

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

The tool is simple with one optional parameter and an output schema, so the description need not detail return values. However, the incomplete parameter semantics and lack of usage guidance leave gaps in what the agent needs to know for correct invocation, preventing a higher score.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'per daftar' but does not explain valid values (integer 1-6 or null) or what null/default means. The parameter's behavior is left ambiguous, forcing the agent to infer from the tool name.

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's function: 'Browse the Masnavi's section list' and details the output: 'Returns titled sections per daftar with beyt counts and ranges.' This is a specific verb+resource+scope that distinguishes it from sibling tools like get_section or find_sections.

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 use for browsing the table of contents, but does not explicitly state when to prefer this over alternatives or mention exclusions. No direct comparison with sibling tools like find_sections or get_range is provided, so guidance is inferred rather than explicit.

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 provided, the description carries the full burden of behavioral disclosure. It transparently explains the verification process and the three possible return statuses, including the concept of fuzzy matching and citation. It also highlights the tool's role in preventing hallucination, which adds behavioral context beyond simple read-only semantics.

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 extremely concise, consisting of two sentences. The first sentence states the function and outcomes, and the second gives a clear imperative usage instruction. Every word contributes to understanding, with no redundancy or 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?

Given the tool's moderate complexity and the existence of an output schema, the description provides sufficient context. It covers the main inputs (quote), the decision logic (exact/fuzzy/not_found), and a strong use-case directive. The only minor omission is detailed behavior of the fuzzy threshold, but this is adequately covered by the schema and the output description.

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 directly explain the 'fuzzy_threshold' parameter, relying on the schema's minimal 'Fuzzy Threshold' label. It does mention fuzzy matching in the output, but without explaining how the threshold affects results, the description adds limited value beyond the schema. The 'text' parameter is well-covered by both schema and description context.

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's function: verifying whether a candidate quote attributed to Rumi's Masnavi actually appears. It names the specific verb 'check', the resource 'Rumi's Masnavi', and distinct outcomes ('exact', 'fuzzy', 'not_found'), making it easy to distinguish from sibling tools like 'search' or 'get_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?

The description explicitly directs when to use the tool with 'USE THIS BEFORE QUOTING RUMI to avoid hallucination', providing clear context. However, it does not mention alternatives or explicitly state when not to use it, which would elevate it to a 5.

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