Mizan

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact — that it pulls live gold and silver prices — implying results vary with market data, but says nothing about defaults with zero inputs, rounding, or what is returned.

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?

A single front-loaded sentence with no filler. It is essentially a copy of the title, so it earns its place as a scope statement but adds little new 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 13-parameter, all-optional calculation tool with no output schema, the description never explains what comes back (zakat due, nisab threshold applied) or that a bare call is valid. It covers the input domain adequately but leaves the agent guessing about the 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%, so all 13 parameters are already self-documenting (grams vs value, nisab enum, defaults for nisab/currency/share_zakatable_pct). The description merely restates the parameter categories and adds no syntax, precedence, or mutually-exclusive guidance 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 names the specific resource (zakat owed) and enumerates the asset classes it covers (cash, gold, silver, shares, business stock), which is concrete enough to separate it from screening/purification siblings. It stops short of naming an alternative or stating the compute verb explicitly, but the purpose is 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?

There is no when-to-use guidance, no prerequisites, and no mention of how this differs from siblings like purify_dividend or screen_portfolio. The agent must infer that this is the tool for computing an actual obligation rather than screening assets.

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

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

Annotations already establish the safe read-only, idempotent, open-world profile, so the description's burden is lower. It adds real behavioral context the annotations don't: result composition (stocks plus index funds), sort order (largest first), and the recency constraint (last quarter-end). It does not state result count or pagination.

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 outcome and the screening criteria, followed by a short call to action. The criteria sentence is dense and nested but every clause carries selection-relevant 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 read-only lookup with one simple parameter and no output schema, the description covers what the results contain, how they are filtered, and in what order. Missing only secondary details like result limits or pagination.

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 documents the single ticker parameter at 100% coverage, including that it accepts a US listing symbol or company name. The description adds no further meaning about the parameter, so the baseline of 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 output (halal alternatives) and enumerates the exact criteria: companies Mizan covers in the same or nearest related industry, business permitted, debt passing all four standards at last quarter-end, ordered largest first, plus Shariah index funds for US/UK investors. This is precise enough to distinguish it from sibling screen tools.

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

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

'Screen a pick live with screen_company before buying' explicitly names the complementary sibling and the workflow step that follows. It gives clear when-to-use context but no explicit exclusion of when this tool is the wrong choice.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds only a fragment ('using live...') before truncating, so any behavioral value it might have conveyed about data freshness or method is lost. It provides essentially nothing beyond the annotations.

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

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

The first sentence merely restates the title verbatim, wasting the front-load position, and the second sentence is truncated mid-clause ('using live...'), leaving the definition structurally incomplete. Not appropriately sized because it literally cuts off.

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 and no parameters, the description carries the full burden of explaining what the tool returns (denominators, thresholds) and when it applies. Because it is truncated and never explains its output or its boundary against screen_company, an agent cannot confidently 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 tool takes zero parameters (schema coverage 100%, empty properties), so there is nothing for the description to disambiguate. Baseline 4 applies, though the schema is trivial enough that no parameter guidance is required.

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

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

The description names a specific resource (the four Shariah equity standards: AAOIFI, Dow Jones Islamic Market, S&P Shariah, MSCI Islamic) and mentions their denominators and thresholds. However, the name 'list_standards' implies a reference-listing tool while the text describes screening 'a US-listed company,' which overlaps heavily with the sibling screen_company, leaving the actual purpose ambiguous. The sentence is also cut off, so the complete intent never lands.

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, no prerequisites, and no mention of alternatives despite siblings like screen_company and screen_portfolio that appear to do the screening work described here. The agent has no signal for choosing this tool over those.

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, non-destructive, open-world behavior, so the safety profile is covered. The description adds real value beyond them: it explains that the ratio comes from the latest 10-K reporting interest income, that 'latest_annual_filing' and 'note' indicate staleness, and that purification cannot rescue a company failed by the business screen.

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 purpose in the first sentence, with no filler. The second sentence is dense with nested clauses and parentheticals, which slightly slows parsing but every clause carries 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?

There is no output schema, so the description must carry return semantics, and it does describe both possible returns (ratio, and charity amount when dividend is given) plus staleness indicators. Remaining gaps like units/currency of the returned amount are minor.

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 adds only the conditional linkage that supplying 'dividend' yields a charity amount. It does not clarify currency handling (dividend 'in any currency') or how the ratio is expressed, so the 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?

States a specific verb-like outcome ('how much of a dividend to give to charity') plus the concrete resource (the purification ratio derived from interest income over total revenue). It is clearly distinguishable from siblings like screen_company, calculate_zakat, and find_halal_alternatives.

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

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

Gives clear context for use: compute the purification ratio, and derive a charity amount when a dividend is supplied. It also flags the boundary case via business_screen for companies excluded by every standard. It does not explicitly route users away from siblings (e.g., when to prefer screen_company), so it stops short of full when/when-not 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description goes further, disclosing non-obvious behavior: 'compliant' is overall verdict and becomes null when the business needs review, 'debt_compliant' is the debt test alone, and verdicts within one percent of a threshold are flagged borderline.

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 purpose is front-loaded in the first clause, followed by a dense but tight enumeration of return fields and their semantics. It is appropriately sized for a tool with no output schema, though the long parenthetical about 'compliant' could be trimmed slightly.

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 and a single well-documented parameter, the description carries the full disclosure burden and does so thoroughly: it names every returned field, the per-standard ratio/threshold/verdict, and the meaning of the null/borderline cases. Nothing needed to interpret the result is missing.

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

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

Schema description coverage is 100%, so the schema already documents the single 'ticker' parameter. The description's note that a common company name (e.g. nvidia) also works largely duplicates the schema's 'a common company name also works', adding no new syntax or format detail, so the baseline of 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?

States a precise verb and resource ('Screen one company against all four standards') and names the exact scope ('one company'), which cleanly distinguishes it from the sibling screen_portfolio. An agent can tell the two apart 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?

Usage is implied by the scope word 'one' against the sibling 'screen_portfolio', so the single-vs-many selection is inferable. However, there is no explicit when/when-not statement, no mention of prerequisites, and no direct routing to the sibling alternatives.

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

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

Annotations already cover read-only, idempotent, open-world and non-destructive behavior. The description goes beyond them by disclosing the 15-holding ceiling and, importantly, describing the return payload: per-standard compliance share, failing holdings, and a combined dividend purification ratio.

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, the purpose leading and return details following — well front-loaded with no filler. The second sentence is dense but every clause (standards count, compliance share, failures, purification ratio) adds 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?

With no output schema, the description usefully enumerates the return shape, and annotations cover the safety profile, leaving few gaps. It does not state error behavior past the 15-holding limit or how weighting affects the results, which would round it out.

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?

Single parameter with 100% schema description coverage, so the ticker:weight syntax is already documented in the schema. The description only adds the aggregate cap (15 holdings), which is marginally useful but not beyond-schema meaning for the parameter itself.

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 (Screen) and resource (a whole portfolio), and the phrase 'whole portfolio' inherently distinguishes it from the sibling screen_company, which presumably handles one company. It also quantifies scope with the 15-holding cap.

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 the 15-holding cap and the portfolio-level framing, but the description never explicitly says when to use this versus screen_company or list_standards, nor what happens past 15 holdings. Adequate context, no explicit routing guidance.

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