RealYield

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new behavior: unspecified agent fee, repairs and voids fall back to standard assumptions, which are surfaced in assumptions_applied, and the tool returns a link that reopens the same deal in the calculator. This is useful beyond the structured hints, though it does not cover rate limits or failure modes.

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 dense sentence that front-loads the resource and then lists outputs, plus a short second sentence on assumptions and the return link. Every clause carries information (yield types, tax, cashflow, stress scenarios), though the output enumeration is long enough to test 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 16 parameters, no output schema and only safety annotations, the description usefully compensates by enumerating what the analysis returns (deal score, break-even rate, stress scenarios) and by explaining how missing inputs are handled. A note on the units/scale of the score or the link's expiry would make it fully self-sufficient.

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 all 16 parameters, their defaults and enums. The description only restates the default-assumption behavior for agent fee, repairs and voids, adding marginal meaning beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Full UK buy-to-let analysis for a purchase price and monthly rent') and enumerates the outputs (yields, Section 24 tax, cashflow, deal score, stress scenarios). An agent can tell it is a comprehensive single-deal analysis. However, it never names the sibling it is not, so the boundary against calculate_section_24_tax, calculate_btl_mortgage or check_deal is left implicit.

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: the breadth of outputs signals 'use this when you want an end-to-end deal view'. There is no explicit when-to-use or when-not-to-use, and no routing guidance toward the narrower sibling calculators that cover single components (Section 24, mortgage, capital gains).

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 fully covered by structured data. The description's added detail is about computed outputs rather than behavior — it says nothing about determinism versus live lender rates, error conditions, or rounding conventions beyond what the annotations imply.

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 the verb first and the deliverables after. It is dense but every listed output earns its place, especially since there is no output schema; a slightly clearer grouping of inputs versus outputs would improve it marginally.

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 returned figures, which is the most important gap to close for a calculator. It omits what the required-vs-defaulted parameter split means in practice and gives no sense of result precision or which figures are null when monthlyRent is left at 0.

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 units, defaults, ranges and an enum already documented per parameter, so the schema does the heavy lifting. The description connects a few concepts to parameters implicitly (ICR to monthlyRent, stress tests to interestRate) but adds no format, unit, or interaction detail 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 opens with a specific verb and resource ('Calculates a UK buy-to-let mortgage') and enumerates exactly which figures are produced (loan amount, LTV, payments, total interest, ICR, stress tests). This implicitly separates it from siblings like analyse_buy_to_let_deal or check_deal, though it never names or contrasts with an alternative.

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, when-not-to-use, or prerequisite guidance. An agent cannot tell from the text whether this should precede analyse_buy_to_let_deal, feed into it, or be used standalone, nor that only propertyValue is required and everything else defaults.

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 (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description goes beyond them by disclosing exactly what the calculation accounts for — allowable costs, private residence relief 'where it applied', the annual exempt amount, rate bands driven by income, and a joint-sale comparison — which tells the agent what the tool will and will not consider.

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 dense sentence, front-loaded with the verb and object, and every listed clause maps to a real output component. It is long but not padded; slight readability cost from packing five items into one sentence.

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 13 parameters and no output schema, the description usefully doubles as a return-value summary, which is exactly what's needed here. It omits tax-year/rate-version assumptions, jurisdiction edge cases (non-UK, non-spouse joint ownership), and any disclaimer that this is an estimate rather than tax advice — modest but real gaps for a tax tool.

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 13 well-documented parameters, so the schema carries the load and the baseline is 3. The description hints at relationships (rate 'based on the seller's income', joint ownership savings) but adds no syntax, units, or defaults beyond what the schema already states.

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 ('Estimates') and a specific, bounded resource ('UK capital gains tax on selling a rental property, shares or another asset'), then enumerates the components computed. It is easily separable from siblings like calculate_section_24_tax or calculate_stamp_duty by subject matter, though it never names a sibling to route against.

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: the enumerated outputs tell an agent this tool applies to a disposal scenario, but there is no explicit when-to-use, when-not-to-use, or alternative routing (e.g. vs. calculate_section_24_tax or the ownership-comparison tool). Nothing is misleading, but the agent must infer the entry 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 establish readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral value by enumerating the computed outputs (tax bill, 20% credit, cashflow after tax, extra tax versus full relief, and all three bands), which matters because there is no output schema. It does not state tax-year assumptions or rounding.

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 that leads with the domain rule and then lists outputs. Dense but every clause carries information; a slightly tighter split into 'what it does' and 'what it returns' would read better, but nothing is wasted.

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 correctly compensates by enumerating return fields, and it explains the core calculation rule. Remaining gaps are minor: no stated tax-year, no note on how annualOperatingCosts interacts with the disallowed interest, and no indication that taxBand only changes which figure is headline.

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 four parameters are already documented, giving a baseline of 3. The description adds marginal nuance that results are also returned for all three tax bands regardless of taxBand, but it does not clarify units, interaction between taxBand and the headline figures, or default behaviour beyond what the schema shows.

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 (calculate) plus the precise domain resource (UK landlord income tax on rental profit under Section 24), including the key mechanic (mortgage interest disallowed, replaced by a 20% credit). This clearly differentiates it from siblings like calculate_capital_gains_tax and calculate_stamp_duty.

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 the tool applies (a UK landlord subject to Section 24 with mortgage interest), but never states when to use it versus the sibling calculators or any prerequisites. No alternatives or exclusions are named, so the agent must infer the routing itself.

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 genuine value by disclosing the shape of the result (band-by-band breakdown, effective rate, cross-buyer-type comparison, total cash needed with deposit), which is important since there is no output schema. It omits any note on rate-table currency/update caveats, but that is minor for a pure calculator.

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?

One dense sentence that front-loads the core purpose and then enumerates the outputs. It is long but every clause carries information (scope, outputs, buyer-type comparison); 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?

With no output schema, the description usefully enumerates the returned figures, and the read-only annotations cover safety for this pure calculation. The main residual gap is the absence of any guidance on jurisdiction limits (e.g. Scotland/Wales not covered beyond the implicit England/NI note) or how the buyer-type comparison relates to the buyerType parameter.

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 schema already documents all three parameters and the buyerType enum. The description adds only marginal semantics, notably the 5% additional-property surcharge, which is not restated in the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (calculates) plus resource (Stamp Duty Land Tax) and scopes it geographically (England or Northern Ireland) and temporally (current rates). A reader can distinguish it from the sibling BTL/CGT/Section 24 calculators immediately.

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 content — you use it when buying a property and need SDLT figures — but the description neither states when to prefer it over siblings like analyse_buy_to_let_deal or calculate_btl_mortgage, nor any exclusions. It hints at coverage (first-time buyer/home mover/additional) without routing the agent.

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

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

Annotations already declare readOnly/idempotent/non-destructive/open-world, so the safety profile is covered. The description adds meaningful context beyond that: it requires an authenticated RealYield account, can take up to 30 seconds, returns a 0-100 score with parts/flags/summary/report link, and results are educational estimates rather than advice.

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-loads the purpose and then covers coverage, return format, caveats and prerequisites. The long enumerations of checked data are dense but earn their place since no output schema exists to describe the report contents; only slight trimming would help.

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 fully carries the burden: it names the geographic scope, the returned score components, flags and report link, plus authentication, latency and the educational-estimate disclaimer. An agent has everything needed to call and interpret this tool.

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% across all 16 parameters, so the baseline is 3. The description reinforces that rent defaults to the ONS area average and that the postcode is the property's rather than the user's location, but these points largely restate what the schema already documents, so it adds only marginal meaning.

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 with clear scope: it checks a specific buy-to-let property in England or Wales using live public data. An agent immediately knows what the tool produces. It does not explicitly distinguish itself from the sibling analyse_buy_to_let_deal, so it falls short of a 5.

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 context is implied (a full deal check on a specific property given its address and characteristics) and it discloses prerequisites (RealYield sign-in) and cost (up to 30 seconds). However, it never says when to prefer this over analyse_buy_to_let_deal or the narrower calculators in the sibling set, leaving routing to inference.

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 safety is covered. The description adds real behavioral value beyond them by specifying the return content: net profit and effective tax rate for each structure plus which structure pays less this year. It does not mention assumptions such as tax-year or rate versions.

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, zero waste, front-loaded with the comparison subject before the return-value summary. 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?

With no output schema, the description correctly compensates by naming the returned metrics and the verdict field. Annotations cover safety, and the schema covers inputs, so the definition is near-complete; only modeling assumptions (tax year, rate basis) are unstated.

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

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

Schema description coverage is 100%, so all five parameters are already documented with units and semantics (including the 'omit to extract all post-tax profit' nuance). The description adds no parameter-level detail beyond the schema, which matches the baseline 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?

States a specific verb ('Compares') and a precise resource: annual tax on a UK rental property held personally (Section 24) vs inside a limited company (corporation tax + dividend tax). This clearly distinguishes it from siblings like calculate_section_24_tax or calculate_capital_gains_tax, which cover only one side of the comparison.

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 comparison scope implies when the tool applies (choosing between personal and company ownership), but there is no explicit when-to-use statement, no prerequisites, and no routing to alternatives such as calculate_section_24_tax for personal-only analysis.

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, closed-world behavior, so the safety profile is covered. The description adds return-shape context not present elsewhere ('returns the definition with a link to the full entry'), which is valuable since there is no output schema. It omits miss behavior (what happens when a term isn't found).

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

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

Two sentences with the verb and scope front-loaded, followed by the usage condition. Efficient and free of filler, though the example list lengthens the first sentence 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?

For a one-parameter read-only lookup with no output schema, the description covers what it does, when to use it, and roughly what comes back. Only the not-found/ambiguity behavior is missing, which is a minor gap at 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?

Schema description coverage is 100% for the single 'term' parameter, so the schema already documents it. The example terms ('ICR', 'Section 24', 'gross yield', 'void period') add mild signal about accepted inputs but no format or matching rules 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 ('looks up a UK property investment or landlord tax term in the RealYield glossary') plus concrete example terms. This clearly separates it from the sibling calculators and search tools, which do not define terminology.

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 explicit usage context: 'Use it when a reader asks what a term in an article means.' It does not name an alternative for the adjacent case (e.g. search_realyield for non-glossary lookups), 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 declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that by disclosing the shape of the return (one-line description and URL per entry).

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, zero waste: the first states what is returned, the second states why to call it. The purpose is front-loaded and the usage note follows naturally.

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 zero-param directory tool with no output schema, the description is nearly complete: it explains what the listing contains and the intent behind calling it. A small gap is the absence of pagination or full-list-size expectations, though that is minor for a static known catalog.

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 document; the empty schema is self-explanatory. Baseline 4 applies for a no-argument tool.

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 (lists) and resource (every UK property calculator on realyield.co.uk), plus the return content (one-line description and URL). This clearly separates it from sibling tools like calculate_stamp_duty or search_realyield, which perform actions rather than enumerate the available 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?

Explicitly says when to use it: 'to find the right tool for a landlord question before navigating or calculating.' That is a clear context, though it does not name the alternative (search_realyield) or state when this directory listing is unnecessary.

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 safety is covered. The description adds genuinely useful context beyond them: the data provenance (ONS rents, HM Land Registry prices) and the monthly refresh cadence. It does not say what happens for an unmatched area name.

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, no filler, and the core capability plus provenance is front-loaded before the usage branch. Every clause carries information an agent needs.

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 still tells the agent what comes back (average rent, average price, gross yield, plus national rank), where the data originates, and how to switch between lookup and ranking modes. Nothing essential for correct invocation 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 baseline is 3, but the description adds cross-parameter behavior the schema does not: 'area' switches between single-area lookup and ranking mode, and 'region'/'limit' are effectively ranking-only modifiers. That linking of parameters to output modes is real added meaning.

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 ('looks up average rent, average price and gross rental yield for local authority areas in England and Wales') with named data sources and coverage. It is unambiguously distinct from the sibling calculators (calculate_stamp_duty, calculate_btl_mortgage) because it is a data lookup/ranking tool, not a computation.

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 branches usage: pass an area name for that area's figures and national rank, or omit it to get the highest-yielding areas, optionally narrowed by region. That gives clear when-to-use-per-mode guidance, though it names no alternative sibling tools for related questions.

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 the safety profile is covered. The description adds genuinely useful return-shape context ('titles, summaries and URLs'), which matters because there is no output schema, but it says nothing about result ranking, pagination, or empty-result 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?

Two sentences, zero filler: the first front-loads the domain and content scope, the second covers the return shape. Nothing repeats the title or name verbatim.

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 correctly compensates by naming the returned fields, and the annotations carry the safety semantics. The remaining gap is routing guidance against the closely related siblings define_property_term and list_realyield_calculators.

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 each of the three parameters (query, type enum, limit) is already documented in the schema, including an example query and the omit-to-search-everything behavior. The description adds no format or syntax guidance beyond what the schema provides, 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?

Specific verb ('Searches') plus resource ('realyield.co.uk') and an enumerated content scope (calculators, articles, glossary terms, templates) with a clear topical domain. It reads as clearly different in kind from the calculate_* siblings, but it does not acknowledge the overlapping siblings list_realyield_calculators and define_property_term, which cover a subset of the same content.

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: an agent can infer 'use this to find content' but the description never says when to prefer it over define_property_term for a glossary lookup or list_realyield_calculators for a calculator listing. No exclusions or prerequisites are stated.

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