Mashkanta-Buddy

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

With only a title annotation, the description carries the full burden and does well: it discloses that the advisor mutates state (correcting facts, pinning insights, notes, presets, candidate mixes) and that these appear in toolsApplied, that the call consumes usage quota, that latency is 20–60 s with progress reporting, and that `disclosure` must be shown to the user. These are non-obvious cost, side-effect, and UX obligations an agent could not infer from the schema.

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

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

Front-loaded with the core action, then cost, latency, and the disclosure obligation in separate sentences with zero filler. The parenthetical enumerating edit types is dense but each item is informative, so it is efficient rather than bloated.

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-param tool with no output schema and no annotations, the description supplies exactly the missing context: side effects and where they are reported (toolsApplied), quota consumption, expected duration, progress feedback, and a required user-facing disclosure field. An agent could invoke and handle the response correctly from this alone.

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 both parameters are already documented, including that mortgageId comes from list_mortgages and the question is in the user's language. The description reinforces the single-mortgage scoping and 'one question' limit but adds no format or syntax detail beyond the schema — 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 and resource — sending one question to the Mashkanta-Buddy advisor about a specific uploaded mortgage — and pins the scope to a single mortgage plus the shared on-site conversation. No sibling tool does advisor Q&A, so it is unambiguously distinguishable from get_mortgage, update_mortgage, or compare_mortgages.

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?

Implies the usage context clearly (answering a user's question about an already-uploaded mortgage, tied to a mortgageId from list_mortgages) and the 20–60 s / quota note signals it is a heavyweight call. It stops short of explicit 'use X instead for quick fact lookups' routing against siblings like get_mortgage.

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), and the description adds real context beyond them: results are deterministic numeric output rather than a rendered page, and inputs are restricted to the user's own mortgages. It does not disclose output shape (which numbers, units, currency) for a tool with no output schema, which keeps it below a 5.

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 capability, then the routing alternative, then use cases — a sensible order with no filler sentences. The trailing Hebrew trigger list is dense but purposeful for intent matching, so it earns its place despite adding length.

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 comparison over one array parameter with no output schema, the description covers purpose, routing, and input constraints. The main remaining gap is what the returned 'numbers' comprise, which the agent must discover by calling — acceptable but not fully 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 coverage is 100% and the single parameter already documents '2 to 3 mortgage ids'. The description restates the 2-3 cardinality and adds the ownership qualifier ('the user's own'), but supplies no format or validation detail beyond the schema. Baseline 3 applies 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 concrete verb+resource ('side-by-side deterministic analysis plus market comparison') scoped to '2-3 of the user's own mortgage ids', and explicitly distinguishes itself from generate_comparison_dashboard ('returns numbers, not a page'). An agent can tell it apart from get_market_comparison and generate_comparison_dashboard 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?

Names the alternative (generate_comparison_dashboard) and the exact condition that selects it ('for a dashboard the user can open'). Adds concrete use-case triggers including Hebrew phrasings for price comparison, refinancing, and early-repayment fees, so intent matching is largely deterministic.

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

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

With no meaningful behavioral annotations beyond a title, the description carries the full burden and discloses key traits: no document is used, the dashboard link is returned immediately with nothing to poll, and typed numbers are never added to the platform comparison pool. It does not cover validation failures or duplicate handling, but the core behavioral profile is clear.

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

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

The description is dense but front-loaded: it begins with the core action and scope, then supplies the track structure, parameter semantics, return behavior, privacy note, and sibling routing. Every sentence contributes to correct invocation, and the Hebrew example clarifies the intended input style.

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 creation tool with no output schema, the description supplies the missing return-value information by stating that it returns the dashboard link immediately. It also covers input structure, alternatives, and behavioral constraints, leaving no material ambiguity for correct invocation.

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

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

Although schema coverage is high, the description adds substantial meaning beyond the schema: tracks are 1–6 rows, each row uses trackType, principal, years, and either ratePercent or primeSpread; trackType allowed values are listed with Hebrew equivalents; primeSpread is explicitly signed with a concrete example; and offerDate format is restated.

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 precise verb and resource: it creates a mortgage from dictated tracks with no document. It also distinguishes this tool from document-based creation by explicitly naming create_upload_ticket as the preferred alternative when a document exists.

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 gives an explicit when-to-use condition with a realistic example, and an explicit when-not-to-use rule: prefer create_upload_ticket whenever a document exists because a document is checkable and typing is not. The routing decision is fully specified.

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 carry no hints (only a title), yet the description discloses the critical behavioral traits itself: the link is PUBLIC and unauthenticated, the operation may reuse an existing link rather than mint a new one, and audio/conversation content is withheld unless includeConversation=true. It also instructs surfacing the `warning` field. It stops short of stating expiration or revocation behavior (revoke_share_links exists as a sibling), which keeps it from a 5.

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

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

Four short sentences, front-loaded with the public/unauthenticated consequence and the explicit-call gate. Every sentence carries actionable content; only the parenthetical "(or reuses)" sacrifices a little clarity for brevity.

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 2-parameter tool with no output schema, the description covers the safety profile, the sharing gate, and the one opt-in flag, and it even references the `warning` return field an agent should relay. It leaves the actual return payload (URL, expiry) unstated, which is acceptable given the absence of an 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 documented in the input schema and the baseline is 3. The description restates that conversation is excluded unless includeConversation=true, giving the flag its privacy consequence, but adds no format or provenance detail beyond the schema for mortgageId.

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 (create/reuse a public dashboard link for a mortgage) and immediately qualifies the scope: anyone with the link can open it without signing in. This is materially different from siblings like get_dashboard or generate_comparison_dashboard, and an agent can distinguish them 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?

"Only call when the user explicitly asks to share" is an unambiguous gating rule that prevents an agent from proactively creating public exposure. It also states the default exclusion of the conversation, which is the main branching decision an agent faces when invoking this tool.

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 carry only a title, so the description bears the full burden and delivers: MIME types, 100 MB cap, single-use link with 15-minute expiry, two delivery forms with field names (browserUrl, uploadEndpoint, curl), and the mandatory polling step. Nothing about the interaction lifecycle is left implicit.

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 capability then return values then follow-up, and every sentence carries information. The trailing Hebrew document-type list is long but functions as domain vocabulary for matching user phrasing, so it mostly earns its space; the text is dense but not padded.

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?

No output schema exists, yet the description fully specifies the return payload shape and expiry semantics, plus the next tool to call. For a one-parameter creation tool this is complete enough for an agent to call it correctly on the first try.

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 single parameter is fully documented in the schema (100% coverage), and the description still adds value by explaining that appendToMortgageId appends pages to an already-uploaded offer rather than creating a new mortgage. The behavioral consequence (pages merged vs new document) is stated, though no ID-format or discovery guidance is given.

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 ('Starts an upload of a mortgage document') with concrete constraints (PDF/JPG/PNG, 100 MB) and names the exact return artifacts. It is clearly distinguishable from siblings like create_share_link and get_upload_status.

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 ('Use when the user has a document to check: ...') and names the required follow-up ('Then poll get_upload_status with the ticket'). It also clarifies the appendToMortgageId case versus a fresh upload, giving the agent a routing decision.

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 only a title annotation, the description carries the full burden and does it well: it discloses that the work is queued/async, that it consumes the AI generation pipeline and usage quota (a real cost signal), and that the deliverable is a link opened on the site rather than readable files.

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, then the async follow-up in the correct order. Slightly dense — the quota parenthetical and the polling/link instructions are packed into two long sentences — but every clause 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?

Async tool with no output schema and no annotations, yet the description covers the entire lifecycle: trigger, returned jobId, polling tool, completion state, and the exact field to surface to the user. An agent can act correctly without further discovery.

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 already documents '2 to 3 mortgage ids from list_mortgages'. The description's '2–3 of the user's own mortgages' adds only the ownership nuance, so the schema does the heavy lifting as expected at baseline.

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 (queues) and resource (a dedicated comparison dashboard) plus scope (over 2–3 of the user's own mortgages). It implicitly separates itself from sibling tools like compare_mortgages and get_market_comparison by emphasizing 'user's own mortgages' and a generated dashboard, but it never names those siblings 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?

Gives a clear precondition (2–3 mortgages, your own) and a full follow-up workflow: poll get_upload_status, then hand over links.site on Completed. It doesn't state when not to use this versus compare_mortgages, so it stops short of a full routing rule.

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 and idempotent behavior, so the bar is lower. The description still adds real context beyond them: that it surfaces quota consumption and whether uploads/advisor are blocked by quota or pending terms, which tells the agent what preconditions it can check.

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 sentence with the resource stated first and the return fields enumerated after; the actionable "call this first" cue lands at the end where it is easy to catch. The field list is dense but every item corresponds to a real output, so little 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?

There is no output schema, so the description carries the return-value burden and does so by enumerating the account fields, quota/blocking status, scopes, and links. With zero inputs, nothing an agent needs to invoke or interpret the call 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. Nothing in the description misrepresents the input surface.

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 (returns the connected account) and enumerates the concrete fields returned: name, email, quota usage, blocked flags, scopes, and site links. This lets an agent distinguish it from the mortgage-oriented siblings 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?

"Call this first in a session" gives a clear, actionable ordering cue that the sibling tools lack. It stops short of naming alternatives or conditions for re-calling, so it is clear but not exhaustive.

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 and idempotentHint, so the safety profile is covered. The description adds genuine value by disclosing that the series is official and that isApproximation flags proxy-derived figures, a data-quality caveat not in annotations. It says nothing about freshness/latency or response shape beyond that, so a 3 is fair.

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 what the tool returns and the approximation caveat before the usage keywords. The Hebrew keyword list is slightly bulky but serves retrieval/matching purposes, so it 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?

With no parameters and no output schema, the description needs to convey the return content, and it does (per-track average rates, isApproximation flag, official series). It does not explain the granularity (e.g., which tracks or date coverage), which is a minor remaining 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 the baseline is 4 by rule. The description correctly implies a parameterless global lookup rather than a per-user query.

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 resource (Bank of Israel average interest rate per mortgage track for newly issued mortgages) and scope (official series, proxy figures flagged by isApproximation). An agent can distinguish it from data-reading siblings like get_mortgage because it explicitly says no uploaded mortgage is required.

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 'Use for:' list with concrete user phrasings (ריביות בנק ישראל, הריבית הממוצעת היום, etc.) gives clear when-to-use context, and 'Needs no uploaded mortgage' implicitly excludes the account-bound tools. It does not name a specific alternative sibling, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds genuinely useful behavior detail — that the dashboard may still be generating and which step it is on — but says nothing about what happens if both or neither ID is supplied, which is the main ambiguity for a caller.

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 resource and its returned state, then the ID rule, then routing phrases. The return list is long but each item is a distinct piece of state an agent may need; the Hebrew keyword block is compact and functional rather than padding.

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 carries the burden of describing return contents and does so thoroughly. The only meaningful gap is error/fallback behavior when the identifier is missing or invalid.

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 field meanings are already documented. The description adds the one thing the schema doesn't encode: that exactly one of mortgageId or miniAppId should be passed. That exclusivity rule is real added value beyond the two nullable UUID properties.

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 clear verb+resource ('the generated dashboard for a mortgage') and enumerates what state is returned (generation step, thesis, archetypes, completeness, warnings, overrides, link). This distinguishes it from get_mortgage, though it never names 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?

It gives concrete invocation context, including Hebrew trigger phrases ('הדשבורד שלי', 'ניתוח המשכנתא') that map a user request to this tool, plus the 'pass either mortgageId or miniAppId' rule. It stops short of stating when NOT to use it or naming an alternative sibling.

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?

Goes well beyond readOnlyHint/idempotentHint: discloses that pool statistics may be SUPPRESSED for small pools, names the two flags to inspect (percentileSuppressed, suppressionReason), and warns never to present a suppressed statistic as a number. It also declares that every figure carries attributed series, period, sample size and vintage — exactly the behavioral context annotations cannot convey.

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 what it measures, then the suppression caveat, then the not-advice scope, then triggers. Dense and mostly earned, though the Hebrew trigger list and the parenthetical provenance detail make it longer than strictly necessary.

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?

No output schema exists, and the description compensates by describing the return shape at a high level (statistics plus provenance, per-track attribution) and naming two output fields. It still doesn't describe the full response structure, so an agent gets only a partial picture of what comes back.

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 and schema description coverage is 100%, with the schema itself pointing to list_mortgages for the id. The description adds no further semantics about mortgageId, 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+resource: statistical position of one mortgage's track rates against the Bank of Israel official average and the platform's consented pool. The scope (single mortgage, benchmark comparison, provenance-bearing statistics) is clear, but the description never names the sibling it differs from (get_boi_rates for raw series, compare_mortgages for mortgage-to-mortgage comparison), so an agent must infer the boundary.

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 a concrete use condition with verbatim user phrasings in Hebrew (האם הריביות טובות, השוואה לשוק, ריבית ממוצעת...) plus a scope exclusion: it does not say whether to sign, refinance or negotiate. That implicitly routes advisory questions elsewhere, though it doesn't name ask_advisor explicitly.

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 annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds important behavioral context: numbers come from document extraction and may be wrong, and callers should show warnings and disclosure. This is useful caveat information beyond the annotations, though it does not discuss error handling or missing-data behavior.

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

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

The description is front-loaded with the main purpose and then lists the returned data and usage contexts. It is appropriately sized for a detail-and-analysis tool, though the long Hebrew keyword list is dense and slightly reduces scannability.

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 explains the return contents in useful detail: tracks, risk score, LTV, scenarios, warnings, assumptions, and disclosure. It is nearly complete for a read-only detail tool, though it could mention what happens if the mortgageId is invalid or 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%, and the single mortgageId parameter is fully described in the schema as coming from list_mortgages. The description adds no additional meaning about the parameter, so the baseline score of 3 is appropriate when the schema does the work.

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 that this tool returns full detail for one mortgage offer, including extracted tracks and deterministic analysis. It distinguishes itself semantically from list_mortgages and compare_mortgages by emphasizing a single mortgage and detailed analysis, though it does not 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 'Use for:' list gives clear contexts such as mortgage mix analysis, tracks, risk score, LTV, and payment-to-income ratio. It does not explicitly state when not to use the tool or name the alternative list_mortgages for discovering mortgage IDs, so it stops short of full routing 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 mark this read-only, so the bar is lower; the description still adds real behavior: the full state machine (Queued/Processing/Completed/Failed), a Hebrew progress line during Processing, and the completion payload. It omits what a Failed result contains or whether errors are returned in-band, which keeps it from a 5.

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 what the tool returns, then timing guidance. Every clause carries information, including the state list and the polling cadence.

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 correctly carries the return-value burden (completion ids and site link, progress text). For a polled read-only status tool it is nearly complete, with only failure semantics and dual-parameter precedence 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 descriptions already identify the origin of jobId and ticket, so the description adds only a restatement of which identifier family each covers. It doesn't say which wins if both are supplied, so baseline 3 is right.

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?

Names the exact resource (upload ticket or job id) and the exact outputs (status states, mortgageId, miniAppId, site link). It is distinguishable from siblings like create_upload_ticket and generate_comparison_dashboard, which produce the identifiers this tool consumes.

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 concrete operational guidance: poll every ~15 s and expect a run of 1–3 minutes, and the schema ties each parameter to the sibling tool that produces it. It doesn't state what to do on Failed or whether to stop polling, but the usage context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered; the description adds valuable behavior beyond that: pagination semantics with total as full count and truncated as a remaining-items flag. It also discloses a non-obvious side effect, that the call additionally returns the user's board sections. The field list compensates for the lack of an output schema.

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

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

Front-loaded with what is returned and in what order, then paging, then the sections side effect, then routing to siblings. The long field enumeration is dense but each item earns its place given there is no output schema.

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 carries return-value burden well: it names every field, explains paging metadata, and covers the extra sections payload. An agent has everything needed to call it and to know which sibling to use with the resulting id.

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 both parameters are already documented, but the description reinforces the default of 20 and explains how limit/offset interact with total and truncated during paging. That is a modest but real addition over the schema's per-field text.

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 (the user's uploaded mortgage offers), clarifies the domain alias ("compositions"), gives the ordering (newest first), and enumerates the returned fields. It is clearly separable from get_mortgage (single item) and compare_mortgages among the 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?

Explicitly routes the agent downstream: use the returned id with get_mortgage / get_market_comparison / get_dashboard / ask_advisor, and notes that section ids are what update_mortgage accepts. It gives clear usage context but no explicit when-not-to-use condition or exclusion versus comparable listing tools.

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 carrying only a title, the description does real work: it discloses the side effects ("stored on the account and the team is notified") and the return behavior ("nothing comes back except confirmation"). It does not mention auth requirements, rate limits, or whether reports are user-visible afterwards, but the mutation and notification semantics are clear.

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 sentences, each earning its place: what it files and for whom, how to fill the parameters, and what happens as a result. The most decision-relevant information (the support-channel framing and the failure classes) is front-loaded.

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

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

There is no output schema, and the description compensates by stating exactly what comes back (confirmation only). For a low-complexity, single-required-param mutation tool, nothing an agent needs in order to call it correctly 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 schema already documents all four parameters including the category enum and the 10–2000 character bound, and the description largely restates them. The one genuine addition is "Pass the user's own words as `message`" — guidance to quote the user rather than paraphrase — which is useful but small.

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+resource ("Files a problem report with the Mashkanta-Buddy team") and then enumerates the exact failure classes it covers — wrong numbers, failed/missing dashboards, stuck uploads, bad advisor answers. That enumeration makes it distinguishable from siblings like create_upload_ticket or get_upload_status 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?

It gives clear triggering contexts (a wrong number, a dashboard that failed, a stuck upload, an off advisor answer) plus a catch-all, and explicitly frames itself as "a support channel, not advice" to steer away from the advisor tools. It stops short of naming the overlapping sibling create_upload_ticket, so an agent must still guess whether a stuck upload belongs here or there.

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 only supply destructiveHint=true; the description adds genuinely new behavioral context: the operation is bulk ('every public share link') and effect is immediate for recipients, so links already distributed break at once. It stops short of saying whether revocation is reversible or whether auth/ownership of the mortgage is required.

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, zero filler. The scope is front-loaded in sentence one and the consequence follows immediately in sentence two.

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 destructive tool with no output schema, this covers the essentials: what is destroyed and how fast. The main omission is whether revocation can be undone or links re-created, which would matter to an agent weighing side effects.

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 a single parameter at 100% schema coverage, the schema already documents mortgageId and even points at list_mortgages as the source. The description adds no further parameter semantics, 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 specific verb (revokes) and resource scope (every public share link of a mortgage's dashboard), which is precisely distinguishable from the sibling create_share_link. The 'every' quantifier makes the bulk nature of the operation unambiguous.

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

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

Usage is implied by the semantics — an agent can infer this is the counterpart to create_share_link — but the description never explicitly says when to call it, nor does it name the sibling or state any precondition (e.g. that share links must exist).

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 only idempotentHint in annotations, the description carries real weight: it discloses partial-update semantics (only supplied fields mutate) and a non-obvious side effect, that linked dashboards are re-seeded with the new values. It does not say what happens on invalid section ids or whether non-owners are rejected, which keeps it out of the top band.

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 tight sentences, zero waste, with the mutation scope and the 'only provided fields change' guard front-loaded before the side-effect note.

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 7-parameter mutation tool with no output schema, the description covers the essential: what is editable, that updates are partial, and that dependent dashboards are affected. It omits error/permission behavior and return shape, but the schema compensates for field-level detail.

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 every parameter in detail, including the empty-string-to-restore-name and all-zeroes-guid unfiling tricks. The description merely restates field names and the yyyy-MM-dd format already present in the schema, adding no semantics 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 ('Owner corrections') plus resource ('one mortgage') and enumerates exactly which facts are editable (name, offer date, property value, income, location, section). An agent can distinguish this from create_mortgage_manual, get_mortgage, and list_mortgages without reading 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?

"Owner corrections" frames the use case (fixing existing records, owner-scoped) and "Only provided fields change" clarifies partial-update intent versus a full replacement. It never names an explicit alternative or when-not condition, so it stops short of the top band.

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