FINLY Mortgage Knowledge

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

Annotations already establish read-only and idempotent behavior, and the description adds the meaningful disclosure that no external rules or identifiers are involved. This tells an agent the tool is a pure arithmetic function with no hidden business logic, going beyond the annotation signal.

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

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

The description is two short sentences and immediately front-loads the operation and its limits. Every sentence adds scope information, and there is no filler beyond the repeated bilingual 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 simple two-parameter arithmetic calculator with read-only annotations, an idempotency hint, and an output schema, the description covers the operation and exclusions sufficiently. The only real gap is the implicit rather than explicit parameter order, but the tool name and parameter names reduce the risk of confusion.

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

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

Schema description coverage is 0%, so the description needed to define the parameters, but it only says 'numerator by denominator' without explicitly stating that loan_agorot is divided by property_value_agorot. The parameter names and title make the mapping inferable, but the description itself does not fully compensate for the empty schema descriptions.

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

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

The description uses the specific verb 'divide' and names the resource as the loan-to-value ratio, making the core operation clear. It also disclaims regulatory caps and eligibility verdicts, which separates it from the more judgment-heavy sibling tools, though it does not name a sibling 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?

The negative constraints ('No regulatory caps, eligibility verdict, fallback rates or customer identifiers') imply this is the tool to use for a raw ratio calculation rather than a full lending decision. However, there is no explicit when-to-use guidance or direct comparison to calculate_payment/calculate_pti_ratio.

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 readOnlyHint, idempotentHint, and destructiveHint, so the description's main contribution is the boundary it sets: this is a hypothetical pure calculation with 'No bank offer, eligibility or savings recommendation.' It also clarifies that money is integer agorot and interest is a decimal, and specifies fixed-rate/unindexed nature—all behaviorally relevant details absent from the structured data.

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 concise sentences with zero filler. The main purpose is front-loaded, followed by necessary unit notation, and a boundary statement—each sentence earns its place.

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

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

The tool has an output schema and comprehensive annotations, so the remaining gaps are small. The description supplies the purpose, the mathematical nature of the calculation, the unit conventions, and the limits of what the tool returns. A little more detail on term_months would push it to a 5, but it's adequate for safe invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It maps 'integer agorot' to principal_agorot and 'annual interest is a decimal' to nominal_annual_decimal, and the phrase 'fixed-rate unindexed annuity' explains how the parameters fit together. However, it doesn't explicitly discuss term_months, leaving that parameter to be inferred from its name.

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

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

The description uses a specific verb ('calculate') and names the resource ('hypothetical fixed-rate unindexed annuity'), making its function unmistakable. It also includes a clarifying boundary ('No bank offer, eligibility or savings recommendation') that helps distinguish it from potential real-world mortgage tools, though it doesn't explicitly name sibling 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?

The description provides useful context: the calculation is hypothetical and explicitly states it is neither a bank offer nor a recommendation, telling the user when not to rely on it. It doesn't explicitly mention alternatives like calculate_ltv_ratio or calculate_pti_ratio, but the sibling names are distinct and the context is clear enough to guide correct usage.

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

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

The description goes well beyond the read-only/idempotent annotations by exposing the exact behavior: a deterministic division of the provided numbers with no hidden regulatory or customer-data logic. This is precisely the kind of behavioral context an agent needs to avoid assuming the tool does more than arithmetic.

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 operation and the key exclusions are each stated in a single short sentence, making the core behavior easy to scan. The opening phrase repeats the title verbatim, which is minor redundancy but not enough to hurt usability.

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 pure calculation with read-only/idempotent annotations and an output schema, the description covers the operation and the absence of hidden rules. The only notable gap is the lack of an explicit numerator/denominator parameter mapping, though the parameter names make that mapping reasonably inferable.

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?

With 0% schema description coverage, the description needed to map the two agorot-denominated inputs to 'numerator' and 'denominator', but it only says 'divide the explicitly provided numerator by denominator'. The parameter names are suggestive, but the description itself does not resolve which input is which, so it only partially compensates for the missing schema descriptions.

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

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

The description uses a specific verb ('Divide') and identifies the resource as 'payment to income', while the negative list ('No regulatory caps, eligibility verdict, fallback rates or customer identifiers') helps separate it from sibling calculators. It is clear, but it does not name an alternative sibling, so the differentiation is implied rather than explicit.

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 gives concrete context about when this tool is appropriate: it is a raw arithmetic ratio and will not apply regulatory caps, issue an eligibility verdict, use fallback rates, or look up customer identifiers. This is clear guidance, though it stops short of explicitly routing to a particular sibling when those features are needed.

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 destructiveHint, so the safety profile is covered. The description adds useful scope information ('currently released', 'approved', 'paginated'), but it does not disclose details like locale constraints or cursor mechanics. Given the annotation coverage, this is adequate but not rich.

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

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

The description is a single front-loaded sentence with no filler or repetition. Every phrase adds meaning, and the core purpose is immediately clear.

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

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

The tool is simple, annotations cover safety, and an output schema exists, so return values need not be described. However, with 0% parameter coverage and no guidance on cursor-based pagination or locale, the description is not fully complete on its own for calling the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the three undocumented parameters. It only hints at 'paginated index', which loosely maps to limit and catalog_cursor, but locale is entirely absent and no parameter is explicitly explained. This is a clear gap.

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

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

The description uses a specific verb ('Discover') and a concrete resource: 'currently released public tools and a paginated index of approved topics, questions, claims and guides.' This clearly identifies a catalog/list operation and distinguishes it from siblings like get_claim, get_guide, or search_public_knowledge, which fetch or search specific items.

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

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

The description implies usage for enumerating available tools and browsing the approved knowledge catalog, but it does not explicitly name alternatives or state when not to use it. It is clear enough in context, yet leaves sibling differentiation 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 cover readOnlyHint and idempotentHint, and the 'Read' wording agrees with them. The description adds only 'versioned' and 'public' context; it does not disclose default-version behavior, missing-claim handling, or other runtime traits.

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

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

A single front-loaded sentence with no filler: 'Read one versioned public claim...' leads with the verb and scope, and every phrase earns its place.

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

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

The output schema and robust annotations supply safety and return-shape details, so the description need not repeat them. It is still thin on how version selection works and does not point to a discovery path, leaving the definition adequate but not complete.

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

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

Schema description coverage is 0%, and the description never maps its wording to claim_id, claim_version, or locale. 'Versioned' gestures at claim_version, and 'scope, evidence and review dates' describes content rather than inputs, so the description does not compensate for the schema's lack of parameter descriptions.

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

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

The description names a specific read operation on a 'claim' resource and qualifies it as 'one versioned public claim' with explicit content fields (scope, evidence, review dates). The singular object and 'Read' verb clearly separate it from the search_* and calculation siblings.

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

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

The description implies that this tool is for retrieving a specific claim version, but it never states when to use it versus search_public_knowledge or how to obtain a claim_id. Usage is therefore only implied, not explicitly guided.

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

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

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint false, the description still adds useful non-obvious context: the content is 'approved,' includes a 'canonical' link, and is explicitly not a recommendation. This helps the agent interpret the result appropriately beyond the schema or annotation metadata.

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 concise sentences with the primary action front-loaded. The second sentence is a meaningful caveat rather than filler, and no words are 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?

For a simple read-only tool with only two constrained parameters, a rich annotation set, and an output schema present, the description covers the essential purpose and an important interpretative caveat. It falls just short of perfect because the guide_id and locale semantics are left entirely to 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 0%, and the description does not mention either parameter. The agent is left to infer the meaning of locale and guide_id from names and schema constraints alone. The description must compensate for the missing parameter documentation, but it does not do so.

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

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

The description clearly identifies the tool's action ('Read approved steps and the canonical FINLY guide link') and its resource (approved guide). The phrase 'A bank guide is not a recommendation' adds a clarifying scope note, but it does not explicitly differentiate the tool from sibling tools such as get_claim or search_public_knowledge.

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

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

No explicit guidance is given for when to use this tool versus the sibling alternatives. The description states what the tool does but does not provide context such as 'use this instead of search_public_knowledge when you need an approved guide' or any exclusion conditions. The final sentence is a clarification, not usage direction.

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 read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond that: the knowledge is 'approved, current public knowledge,' results are catalog-based, and free text/personal data are not accepted. This gives the agent a clearer operational picture without contradicting 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 description is one efficient, front-loaded sentence with a second short exclusion sentence. Every phrase adds value, and there is no filler or repetition of the tool name.

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

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

Given the rich annotations and presence of an output schema, the description covers the main selection and invocation context: what kind of data is searched, what inputs are allowed, and what is prohibited. Minor gaps remain around whether topic and question_id are mutually exclusive or whether pagination parameters are needed, but these are not severe.

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

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

Schema description coverage is 0%, so the description must compensate. It does clarify the two central parameters by saying lookup is by 'catalog topic or question ID' and that free text is not allowed. However, it says nothing about limit, cursor, or locale, leaving pagination and output language semantics to be inferred from the schema and output 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 uses a specific verb and resource: 'Find approved, current public knowledge by a catalog topic or question ID.' It also sets boundaries ('No free text or personal data') that distinguish it clearly from the sibling search_public_knowledge tool, so the agent can tell which tool fits its task.

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 gives clear context for when to use the tool: when the query is a catalog topic or question ID. It also states a firm exclusion ('No free text or personal data'), which prevents misuse. It does not explicitly name an alternative sibling or say 'use search_public_knowledge for free text,' so it stops just short of a 5.

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

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

With annotations covering readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds valuable context: it clarifies that retrieval is local and lexical, returns exact evidence and limitations, and does not store or echo the query. This goes beyond the annotations by describing the non-storing behavior and the lexical approach, which is helpful for agents to set expectations on privacy and retrieval style.

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

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

The description is concise, with two sentences that are efficient and front-load the purpose. The first sentence states the action and resource, the second adds constraints and behavioral details. No wasted words, but it could be slightly more structured with separate sentences for clearer readability. It earns a 4 for being direct and informative.

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

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

Given the tool's simplicity, annotations indicating a safe read operation, and an output schema (which presumably describes the return format), the description is fairly complete. It covers the query language constraint (Hebrew), the general nature of the query, and key behavioral limitations (no storage, no personal data). It could mention that it only searches approved public claims and bank guides, but it does. Minor gaps like parameter explanations are present but not critical.

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

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

The schema coverage is 0%, meaning the description must compensate for undocumented parameters. The description explains the 'query' parameter by indicating it should be a short general Hebrew question)Skip with no personal details. However, it does not explain 'limit' or 'locale'. 'locale' has a default in schema (const 'he') but that's clear from schema. Since the description provides some context for the main parameter but leaves others unaddressed, a 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 clearly states the tool searches approved public claims and bank guides using a short general Hebrew question. It specifies the input type (short general Hebrew question) and the scope (public claims and bank guides), distinguishing it from sibling tools like search_mortgage_knowledge which likely searches broader mortgage knowledge. The purpose is specific and concrete.

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

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

The description clearly indicates when to use this tool: when the user asks a general question about public claims or bank guides, and provides constraints (no personal details, numbers, links). It implies the tool is for public information retrieval, contrasting with sibling tools like get_claim or get_guide which may fetch specific claims. However, it does not explicitly state when not to use it or name alternatives, but the context is sufficient for an agent to infer usage.

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