Halal or Not

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add behavioural detail — and it does: it discloses that responses contain a verdict plus scholarly views plus halal alternatives, and that single ingredients and E-numbers are recognised inputs. That return-shape and input-tolerance information is genuinely useful and not derivable from 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?

Front-loaded with the purpose, then dense parenthetical domain lists that carry real information rather than filler. The single long third sentence is slightly run-on, but nothing is wasted and the coverage list doubles as a scoping statement.

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 explain returns — and it does (verdict, scholarly views, alternatives). Input is fully documented by the schema. The only real gap is the unresolved overlap with the specialised sibling tools, which the description never addresses.

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 with 100% schema description coverage that already includes a worked example ('Is a credit card halal?'), so the baseline is 3. The description adds only a mild hint about acceptable input forms ('recognises single ingredients and E-numbers'), which is useful but marginal.

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 ('Ask') and resource ('is it halal' question) and enumerates the covered domains concretely, so the agent knows this is a broad religious-verdict Q&A tool. It does not, however, distinguish itself from specialists like check_crypto, check_medicine or check_ingredients, which cover overlapping territory.

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?

Usage is implied rather than stated: the breadth of the domain list signals 'open-ended questions go here', but there is no explicit when/when-not and no routing rule against the sibling check_* tools. An agent must infer whether 'Is Bitcoin halal?' belongs here or in check_crypto.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds useful output behavior by stating it classifies coins into categories (lending, gambling, meme, stablecoin, staking, general-purpose) and returns scholarly views.

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

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

The description is short and front-loads the purpose, but its first sentence exactly repeats the tool title, which is redundant. The second sentence carries all the substantive detail efficiently.

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 read-only tool with one well-documented parameter and no output schema, the description gives enough context: it explains the classification categories and the scholarly views returned. Annotations cover safety, and parameter details are in the 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 100%, and the schema itself documents the coin parameter with examples like bitcoin, ETH, and AAVE. The description adds no extra parameter semantics, so the baseline of 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 states a specific resource (cryptocurrency) and action (classify by function and provide scholarly views). It is clear what the tool does, but it does not explicitly differentiate itself from sibling tools like ask_is_it_halal.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as ask_is_it_halal or screen_stock. The title implies cryptocurrency-specific use, but the description provides no when-to-use or when-not-to-use 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?

Annotations already confirm readOnly/idempotent/non-destructive, so the bar is lower, and the description adds real behavior: it reads the latest SEC holdings report and screens each holding by industry and debt, and it uses an index-tracking proxy for UK listings. It stops short of stating latency, coverage limits, or what happens on unresolvable tickers.

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

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

The opening sentence is front-loaded, but the title is then repeated verbatim as the first sentence, and the final sentence is a dense run-on mixing UK tickers, fund names, and index-proxy behavior. It could be tightened without losing 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?

For a single-parameter, no-output-schema lookup, the description gives enough about the resolution logic and data source to call it correctly. Only the unresolvable-input behavior and possible response latency are unaddressed.

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

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

Schema coverage is 100% and the schema already documents that the ticker accepts a fund/ETF ticker or a Shariah fund name. The description only adds extra UK example tickers (VUSA, CSPX, VWRL), which is marginal value over the schema, so the baseline 3 applies.

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

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

The description names a specific decision ('is this fund/ETF/pension fund halal') and the resource it operates on, and the screening mechanism (Shariah recognition, SEC holdings, index proxies) makes it clearly distinct from siblings like screen_stock or check_crypto. An agent can pick this over the alternatives 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 implicitly routes three cases: Shariah funds by name/ticker, other US-registered funds/ETFs via SEC filings, and UK-listed ETFs/names via an equivalent US index fund. That covers when each path applies, but it never states exclusions or explicitly points to the sibling that handles individual equities (screen_stock).

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, and openWorldHint=false, so the safety profile is covered. The description adds the return shape (overall verdict, per-school verdicts, flagged ingredients with reasons), which is valuable since there is no output schema, though it doesn't explain what the verdicts mean or how schools are treated.

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 sentences, front-loaded with the action, then input guidance, then return shape. No filler, though the opening sentence restates 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?

For a two-parameter, annotation-covered read tool with no output schema, the description covers the action, input expectation, and return contents. It leaves the meaning of 'school' verdicts and the effect of the context enum to the schema and sibling tools.

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, including the enum meanings for context. The description only reinforces the ingredients format ('exactly as printed'), which slightly conflicts with the schema's 'comma separated' phrasing but adds little beyond it.

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 (check) and resource (an ingredients list) plus the exact input form to supply. It doesn't explicitly name a sibling to contrast with, but the 'pass the printed ingredient text' framing implicitly separates it from barcode- or product-based siblings like check_product_by_barcode.

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 input-format instruction ('pass the ingredients exactly as printed on the pack'), which is a genuine usage hint, but never says when to choose this tool over check_medicine, check_product_by_barcode, or ask_is_it_halal, and never explains when to set the context parameter.

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 safety (readOnly, idempotent, non-destructive) and world scope, so the description is free to add the substance it does add: the openFDA US-label source, the specific flagged substances (gelatine, alcohol, pig-derived enzymes, heparin), and the output shape where the necessity ruling leads. That is genuine context beyond the structured fields, though it does not cover limits such as label unavailability or non-US products.

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

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

The opening fragment 'Is this medicine halal?.' duplicates the title verbatim and wastes a sentence slot, and the second sentence is a dense semicolon splice mixing output-field naming with product guidance. The useful information (source, flagged substances, output ordering) is present but not cleanly 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?

With no output schema, the description usefully names the leading fields (ingredient_headline, verdict) and explains the ordering rationale, and annotations carry the safety profile. It is close to complete for a single-parameter read tool, with the only gap being behavior when a label is missing or the medicine is not in openFDA.

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?

There is a single parameter with 100% schema description coverage ('Brand or generic name'), so the schema does the heavy lifting and the baseline is 3. The description adds nothing about accepted name formats (brand vs generic resolution), so it neither compensates nor detracts.

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

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

The description states a specific verb and resource (reads a medicine's label and flags haram-relevant ingredients) and names the data source (US label / openFDA), which distinguishes it from the generic check_ingredients sibling. It stops short of explicitly contrasting itself with ask_is_it_halal or check_ingredients, so sibling differentiation is only implicit via the openFDA-medicine 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?

Usage is implied rather than stated: an agent can infer this is for checking a named medicine, and the closing clause about the ruling on necessity signals that prescribed medicines should not be discouraged. There is no explicit when-to-use, when-not-to-use, or naming of the alternative sibling tools, so the agent must infer routing.

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 safety and determinism are covered. The description adds genuinely new behavioral context: the lookup is a fallback chain across two external databases before the ingredient check, which annotations cannot express. It does not cover failure behavior for an unknown barcode.

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 action before the implementation detail. Efficient, though 'checks its ingredients' is slightly vague about what the check yields.

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 single-parameter read tool the description is serviceable, but with no output schema it gives no hint of the return shape (ingredient verdicts, unknown-product handling, which source answered). Something an agent needs to 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?

There is a single required parameter with 100% schema description coverage ('EAN-13, EAN-8 or UPC barcode digits'). The description adds nothing about the barcode format beyond the schema, so the baseline of 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?

States a specific verb and resource ('Check a product by barcode') and names the exact data sources it queries (Open Food Facts, then Open Beauty Facts) plus the ingredient check. It is clear what the tool does, though it does not distinguish itself from the sibling check_ingredients, which sounds like an overlapping capability.

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?

Usage is only implied by the name and the word 'barcode'. There is no statement of when to prefer this over check_ingredients, search_products, or check_medicine, nor any prerequisite or exclusion. An agent must guess at the routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds context annotations cannot carry: the tool returns a verdict per school plus reasoning, and it is scoped to a single item. With no output schema, this return-shape disclosure is genuinely load-bearing, though nothing is said about verdict vocabulary or unknown-ingredient handling.

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, front-loaded with purpose, then examples, then the return contract. No filler, no restatement of the title, and every sentence carries information the agent can act on.

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, read-only, two-parameter lookup whose annotations cover the safety profile, the description supplies purpose, input examples and output content. It stops short of explaining the 'context' enum's effect or what a verdict/school value can be, which slightly under-serves a tool with no 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 100%, so both parameters are already documented, and the description's examples simply mirror the schema's own 'E471, carmine, gelatin or alcohol denat' wording. The 'context' parameter (food vs cosmetic, defaulting to food) is never mentioned, so the description adds no 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?

States a specific verb and resource ('Explain one ingredient or E-number') and emphasizes the singular scope, which implicitly contrasts with the batch-oriented sibling check_ingredients. The examples ('E471', 'carmine', 'prawns', 'whey', 'alcohol denat') pin down the input domain, and it even names the output ('verdict for each school and the reasoning').

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

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

No explicit when-to-use, when-not, or alternative selection is given; the agent must infer that this is the single-item lookup counterpart to check_ingredients. Usage is implied adequately by the examples and the 'one ingredient' framing, but no sibling is ever named.

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 readOnly=true, idempotent=true, openWorld=false, and destructive=false, so the safety profile is covered. The description adds content-scope context (agreement vs. disagreement plus reasoning and halal alternatives), but it stops short of describing answer format or depth.

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 scope is front-loaded in the first sentence, which is good, but the second sentence is a sprawling run-on that crams in many categories and then terminates mid-word ('halal alt...'), suggesting truncation and hurting readability.

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 parameters, no output schema, and annotations covering safety, the description carries most of the burden and does convey what the answer contains (agreement/difference, reasoning, alternatives). The truncated tail is the only meaningful gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The domains listed (food, cosmetics, medicine, stocks, crypto, money products) actually serve as an implicit topic taxonomy, which is a small bonus.

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+resource: it explains how the four Sunni schools differ and answers halal questions across concrete domains (food, cosmetics, medicines, stocks, etc.). This separates it from the single-item verdict siblings like check_ingredients or check_medicine, though it does not name them 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?

Usage is implied rather than stated: an agent can infer it is for comparative/madhhab-level explanation rather than a single product verdict, but there is no explicit when-to-use or when-to-prefer-siblings 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that (no note on method defaults, calculation variance, or geocoding behavior) and actively muddies behavior by advertising halal-ruling functionality this tool does not perform.

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 text is a truncated run-on ('...with the reasoning and halal alt...') whose second half is unrelated to the tool, so it is both wasteful and misleading rather than front-loaded and economical.

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 five optional parameters and no output schema, the description should at minimum explain defaults (date defaults to today, method default unspecified) and what the response contains. Instead it spends its length on an unrelated capability, leaving the agent with gaps around default method selection and result shape.

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%, with every parameter documented including the enum values and the lat/lon-vs-city exclusivity, so the baseline of 3 applies. The description contributes no additional parameter meaning and, given its truncated tail, adds no syntax or default details 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 opening sentence states a specific verb and resource: 'Today's prayer times for a place, with both Asr times and Ramadan suhoor and iftar.' However, the remainder of the description describes an entirely different capability ('answers is it halal? for food, cosmetics, medicines, stocks...'), which belongs to sibling tools like ask_is_it_halal and screen_stock, so an agent cannot trust the stated 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?

There is no guidance on when to use this tool versus alternatives, nor how to choose between the city parameter and the lat/lon pair. The description never mentions the sibling tools that overlap with its contaminated second half, leaving the agent to guess.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds real content-level disclosure: it includes the reasoning and halal alternatives and marks scholarly disagreement across schools. It does not, however, say how large the payload is or whether results are scoped/paginated — a notable omission for a tool called 'the full rulebook' with no parameters.

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?

It leads with a short, punchy framing sentence ('The full rulebook.') and then enumerates scope in one clause. No filler, though the dangling, truncated ending ('with the reasoning and halal alt...') suggests the description is cut off and not fully polished.

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 must carry the burden of explaining what comes back, and it only partially does: it says reasoning and school-level agreement/disagreement are included, but nothing about volume, structure, or how an ambiguous query behaves. For a no-argument global reference tool, that is adequate but leaves real gaps.

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 per the rubric the baseline is 4. There is nothing parameter-wise the description could usefully add, and it does not introduce spurious argument talk.

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 broad coverage domains (food, cosmetics, medicines, stocks, funds, crypto, money products, everyday life) and the comparative angle (agreement/difference among the four Sunni schools), which is specific enough to picture the content. However, it opens by saying it 'Answers is it halal?' — a job that the sibling ask_is_it_halal appears to own — so the agent cannot cleanly tell list_rules and ask_is_it_halal apart from the text alone. The resource being listed (rules) is never stated 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?

There is no when-to-use guidance at all. With nine sibling check_*/ask_* tools that also answer halal questions, the description gives no condition that selects this tool (e.g., 'use when you want the full comparative rulebook rather than a single product verdict'). The agent must infer the routing from the tool name.

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, and non-destructive behavior, so the safety profile is covered. The description adds content-level context about showing scholarly agreement and reasoning, but it does not add behavioral details such as result format, pagination, or how the answer is produced.

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 truncated, run-on sentence ending in 'halal alt...'. It is not front-loaded with a clear action and wastes space on broad subject matter rather than concise tool-specific 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?

For a listing tool with one optional filter parameter and no output schema, the description should clarify what is returned and how the category parameter affects results. Instead, it describes the rulebook's coverage and never confirms that list_topics returns a list of topics.

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 category parameter is fully documented in the schema with an enum. The description does not explain how category filtering works and even lists broader areas such as cosmetics and stocks that do not match the enum values, but the schema already carries the parameter semantics.

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 name is list_topics, but the description never states that this tool lists topics. Instead it says it 'Answers is it halal?' and covers scholarly agreement, which sounds like the purpose of a sibling tool such as ask_is_it_halal. The first sentence is a restatement of the title rather than a clear verb+resource statement.

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 given about when to use this tool rather than ask_is_it_halal, list_rules, or any of the other sibling tools. The listed domains imply broad coverage but do not tell an agent when to choose list_topics specifically.

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 the safety profile (readOnly, idempotent, non-destructive, openWorld=false), so the bar is lower; the description adds real behavioral context by disclosing the two-stage process (business/excluded-industry screen, then AAOIFI, Dow Jones, S&P and MSCI debt screens) and that results include links to halal alternatives. No output schema exists, so this return-value disclosure is genuinely valuable.

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 core question and then the screening detail, with no filler. The only slight waste is the opening sentence repeating the title verbatim, which costs a few tokens without adding 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?

For a one-parameter tool with no output schema, the description does enough: it explains the input flexibility and the shape of the answer (per-standard screens plus alternative suggestions). It could go one step further by stating explicitly what the response contains per standard, but nothing essential 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 the parameter is already documented as a US ticker (AAPL, TSLA); the description adds meaning beyond the schema by noting a company name is also accepted and giving examples (nvidia, philip morris). That is a useful expansion of the accepted input format rather than a restatement.

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 ('Screens a US-listed stock via Mizan') and details the screening pipeline, which distinguishes it from the fund, crypto and product-checking siblings. The scope word 'US-listed stock' is enough for an agent to route correctly without opening any 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?

The description implies when to use it ('A company name also works (nvidia, philip morris)') by clarifying accepted inputs, but never names when to prefer a sibling such as check_fund or check_crypto, nor any exclusion. Usage is inferable but not explicitly routed.

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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds meaningful behavior beyond that: it caps results at five, explains the verdict plus 'say' line, and discloses the brand_statement resolution rule ('that statement decides it and is quoted'). It stops short of describing ranking or failure 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?

Front-loaded with the action and scope, and every sentence carries information about inputs or returns. The second sentence is dense but earns its length by explaining the return shape and the brand_statement rule.

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 must carry return-value context, and it does: match count, verdict per match, 'say' line, and brand_statement. Combined with full schema coverage and read-only annotations, an agent has enough to invoke it correctly; error/empty-result handling is the only omission.

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, including the barcode example and country slugs. The description adds only the illustrative 'Haribo Starmix' example, so it sits at the baseline for a fully documented 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?

States a specific verb and resource ('Find products by name and check them', 'Searches Open Food Facts by name or brand') and describes the output shape (up to five matches, a verdict, a 'say' line). It does not explicitly name the sibling check_product_by_barcode, which also accepts a barcode via 'q', so the boundary is left slightly ambiguous.

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?

Usage is implied by 'searches by name or brand' with an example query, so an agent can infer the lookup use case. However, there is no explicit when-to-use statement, no stated alternatives to check_product_by_barcode or check_ingredients, and no exclusion criteria.

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