IDX Broker MCP by usefulapi

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

Annotations already declare write, non-idempotent, non-destructive, and open-world behavior, so the bar is lower. The description still adds real value beyond them by disclosing who can see the note and that a new note id is returned, though it says nothing about permissions or failure behavior.

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

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

Three short fragments with the operation type front-loaded first and the endpoint last; every element (verb, scope, return value, route) carries information an agent would otherwise have to guess at.

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 mutation with no output schema, the description covers the essentials: what is written, who sees it, and what comes back. Only edge behavior (invalid lead id, oversize note handling) is left unaddressed, and the schema's maxLength covers part of that.

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 both lead_id and note documented including length bounds, so the description does not need to compensate. It adds no syntax, formatting, or ID-sourcing detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('adds a note to a lead'), scopes the effect ('visible to the account's agents'), and names the return value and underlying endpoint. This is clearly distinguishable from idx_list_lead_notes and idx_update_lead without opening any schema.

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

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

The 'WRITE:' prefix and the visibility note imply this is for appending agent-visible notes rather than reading them (idx_list_lead_notes) or editing the lead (idx_update_lead), but no alternative or when-not-to-use condition is stated explicitly. Usage must be inferred from the verb.

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 as non-read-only, open-world, non-idempotent, but the description adds real behavior beyond them: it may trigger the account's own lead notifications, valid MX records are required, bad addresses surface as a server error, and the new lead id is returned. That is exactly the side-effect and failure-mode disclosure an agent needs before a write.

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 tight sentences, front-loaded with the WRITE marker and effect, then prerequisites, then field mechanics, then return value. No sentence is filler.

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 supplies the return value ('the new lead id'), the mutation's external side effect, the validation constraint that causes hard failures, and how to address nested `fields`. Nothing needed for a correct 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?

Schema coverage is 100%, so the baseline is 3, but the description adds the email MX-record precondition, which the schema does not express, and routes discovery of `fields` keys to idx_get_lead. It complements rather than repeats 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?

Opens with an explicit verb+resource+scope: 'WRITE: creates a new lead in the IDX Broker account', immediately distinguishing it from idx_update_lead and idx_get_lead in the sibling set. The trailing 'PUT /leads/lead' anchors the operation to a concrete endpoint.

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 'creates a new lead' framing plus the pointer to idx_get_lead for discovering field names gives clear context for the create path. It never explicitly says to use idx_update_lead for existing leads or when not to create a duplicate, so exclusions are left implicit.

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/openWorld/non-destructive, so the description spends its words well beyond that: it explicitly guarantees access keys and passwords are never returned (a security-relevant guarantee not in the schema) and discloses that the response includes hourly API quota consumption, which is operationally important.

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 compact sentences front-load the core identification, then add the two details an agent most needs (no secrets returned, quota usage included), closing with the endpoint path. Nothing is redundant with the title beyond the unavoidable identification of the resource.

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 return-value explanation and does so at a reasonable level: company/contact details, account settings, and rate-limit usage. Minor gaps remain — response shape granularity and whether the quota figure is a count vs. a limit are unstated — but the essentials are covered.

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 to disambiguate; the schema is empty and coverage is effectively complete. The description correctly spends no space on parameter explanation.

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 — retrieves the IDX Broker client account associated with the access key — and names the key contents (company/contact details, account settings, hourly API usage) plus the underlying endpoint. It is distinguishable from siblings like idx_get_account_type by describing the returned payload, though it never explicitly contrasts with that near-namesake.

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: a no-parameter read that tells you about 'the access key' in use. There is no statement of when to call this versus idx_get_account_type or the various idx_list_* account sub-resources, and no prerequisites or exclusions.

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 and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: the two plan values and the derived rate limits (300/key on Lite, 500 on Platinum), which is exactly the operational context an agent needs when budgeting calls.

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 plus endpoint, front-loaded with what is returned and why it matters. The trailing 'GET /clients/accounttype' is transport detail of marginal use to an agent but costs little.

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 input params, no output schema, and read-only annotations, the definition covers the essentials: what is returned and its practical consequence. A one-line statement of the response shape (string enum) or overlap with idx_get_account_info would close the 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 there is nothing for the description to disambiguate. Baseline for a no-param 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 resource and return value: the IDX Broker plan of the account (Lite or Platinum), and the raw endpoint. However, it does not differentiate from the sibling idx_get_account_info, which an agent would reasonably consider interchangeable for 'tell me about my account'.

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

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

Usage is only implied by the content: the plan governs the hourly API limit, which hints at why you'd call it (capacity/quota planning). There is no explicit when-to-use, when-not-to-use, or named alternative such as idx_get_account_info.

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, destructiveHint=false and openWorldHint=true, so the safety profile needs no restating. The description earns credit by disclosing the response shape — a single lead plus a bounded sample (last 5) of viewed listings and searches plus a total count — which matters since no output schema exists. It stops short of covering error cases, not-found behavior, or whether 'details' is stable across accounts.

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 payload contents, followed by the endpoint path. The 'GET /leads/lead/{leadID}.' clause is largely redundant with the name and id parameter, but it is short and does not obscure the useful content.

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 read with no output schema, the description supplies the essential return-value picture an agent needs to decide whether to call it. Minor gaps remain — no mention of what fields appear in 'details' or of failure behavior for an unknown lead id — but nothing critical is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description confirms the id-based lookup and the single-record scope, but adds nothing about the optional `fields` projection parameter (which the schema already documents as an rf-style field filter).

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 and resource: fetches one lead by id and enumerates what comes back (details, last 5 viewed listings and searches, total listings viewed). It contrasts implicitly with the plural idx_list_leads, but never names the sibling to make the distinction 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?

Usage is only implied: you need a single lead and its engagement summary, so you call this. There is no stated when-to-use/when-not, no note on how it differs from idx_list_leads or idx_get_lead_traffic, and no prerequisites such as where the lead id comes from (that hint lives in the schema, not the description).

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, non-destructive and open-world, so the safety profile is covered; the description adds a real behavioral constraint beyond that: a hard cap of 5,000 rows per request and the narrowing strategy. It stops short of disclosing ordering of results, auth requirements, or whether the row cap truncates silently.

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 dense sentences: payload contents first, then the pagination constraint, then the endpoint. No filler and the most decision-relevant fact (5,000-row cap) 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?

With six parameters, full schema coverage, annotations and no output schema, the description supplies the missing return-value picture (fields returned) and the row cap. What remains unsaid — result ordering, truncation behavior, and permission requirements — is minor but non-zero for a paginated history endpoint.

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%, including the interval bounds and offset/limit semantics, so the schema does the heavy lifting. The description only reiterates the narrowing trio without adding relationships (e.g., how interval interacts with start_datetime) beyond what the schema 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 resource (per-lead website traffic history) and enumerates the returned fields (date, page, referrer, IP), plus the underlying endpoint. An agent can tell this apart from siblings like idx_get_lead or idx_list_lead_searches without inspecting any schema.

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

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

The description is about how to shape the request (interval/offset/limit) rather than when to choose this tool over alternatives. Usage is inferable — pull visit history for one lead — but no sibling is named and no exclusion or prerequisite is given.

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 and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the timestamps are UTC and cover two distinct pipelines (feed download/process vs image gathering) rather than a single 'last updated' value. With no output schema present, it still leaves the exact field names and shape unstated.

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 compact elements, information front-loaded with the endpoint appended for orientation. No filler sentences. The stacked 'when ... and when ...' construction is slightly dense on first read but remains parseable.

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 low-complexity, two-parameter read tool with fully documented schema and non-destructive annotations, the description covers the essential unknown: what freshness data is returned and in which timezone. Only the precise response field names are left implicit, which is a minor gap since no output schema exists.

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%: idx_id names the IDX MLS id format and points to idx_list_approved_mls, and fields explains the rf projection including ["*"] and the size-saving rationale. The description adds nothing about either parameter, so the baseline 3 applies.

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

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

The description names the resource precisely: an MLS feed's last download/process time and its images' last-gathered time, in UTC, scoped to /mls/age/{idxID}. It is clearly a read of freshness metadata rather than listings or MLS enumeration, so it is distinguishable from siblings such as idx_list_approved_mls. The phrasing is a noun clause rather than a verb+resource, which keeps it just below 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?

There is no statement of when to call this versus alternatives (e.g. before relying on cached listing data, or after triggering a feed). No prerequisites, no exclusions, no sibling routing are given. The agent must infer usage entirely from the name and return description.

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, destructiveHint=false and openWorldHint=true, so the safety profile needs no restatement. The description adds a bit beyond that by framing the result as a live point-in-time match count and citing the underlying HTTP route, but says nothing about cost, staleness or error behavior when the saved link id is invalid.

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 semantic meaning of the return value comes first and the endpoint reference follows as supporting detail. Nothing could be removed without losing information.

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

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

For a single-parameter, annotation-covered read with no output schema, the description conveys enough to call it correctly, and 'the total number of properties' makes the return type (an integer count) obvious. Only the missing cross-reference to idx_list_saved_links as the full-results alternative keeps it from perfect.

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 one parameter at 100% schema description coverage, the schema already explains saved_link_id and even points to idx_list_saved_links as its source. The description confirms the id identifies the saved link being counted but adds no format, range or derivation detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb-and-resource: returns the total number of properties a saved link currently matches, and pins it to the concrete endpoint GET /clients/savedlinks/{savedLinkID}/count. It is clearly a read of a count rather than a listing, though it never names idx_list_saved_links as the sibling that returns the underlying properties.

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 word 'count' plus 'currently matches' suggests this is the lightweight alternative to fetching the full matching set, but the description never says when to prefer it over idx_list_saved_links or what precondition (a saved link must already exist) applies.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only that the response includes the widget's settings, and says nothing about error behavior for unknown ids or what 'settings' comprises, which matters since there is no 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?

Two short fragments, zero waste, and the resource is front-loaded before the endpoint. The lead is a noun phrase rather than a verb phrase, which makes it slightly less immediately actionable than a full 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?

For a simple two-parameter read with full schema coverage and a complete annotation set, the description is adequate but thin: with no output schema, it should at minimum sketch the returned widget shape, and it gives no guidance on failure for a bad 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 description coverage is 100%, and both parameters are documented there, including the fields projection and the 'from idx_list_widgets' provenance of widget_id. The description contributes no additional parameter meaning, so the baseline 3 applies.

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

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

The description names a single resource ('One JavaScript widget with its settings') and the underlying endpoint, so the agent understands it is a single-item fetch. The singular 'One' implicitly contrasts with idx_list_widgets, though it never names that 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?

There is no statement of when to use this tool versus idx_list_widgets or any other sibling. The only routing hint, that widget_id comes from idx_list_widgets, lives in the schema rather than the description.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds that the scope is a multi-user account and names the underlying endpoint, but says nothing about pagination, result size limits, or authentication requirements — notable gaps for an open-world list call.

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

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

Three short sentences with the resource and return payload front-loaded and the endpoint tucked at the end as reference. Nearly every clause earns its place, though 'GET /clients/agents' is redundant for tool selection.

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 does useful work by naming the returned fields, and it gestures at both filtering modes. Missing are pagination/result-count behavior and any indication that all six parameters are optional, which matters for an agent deciding whether a bare call is valid.

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 fields, interval, date_type, filter_field, filter_value and start_datetime in detail. The one added bit of meaning is the pairing constraint between filter_field/filter_value and the interval window, which the schema does not state explicitly; that keeps it at baseline rather than below.

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 ('Agents on a multi-user IDX Broker account') and enumerates the fields returned, so an agent can tell it lists account agents rather than offices or leads. It never names or contrasts the nearest siblings (idx_list_offices, idx_list_leads), so differentiation is inferred from the resource name alone.

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?

'Filter by one field or by a time window' hints at two mutually exclusive retrieval modes, which is genuinely useful usage guidance. However, there is no statement of when to prefer this tool over sibling list tools, no prerequisites, and no note on what happens if filter_field is passed without filter_value.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, open world), and the description adds context beyond them: results are account-scoped ("approved for display on the account") and carry IDX ids and names. It stops short of describing result size, ordering, or any pagination/rate 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 plus the endpoint: the return content is front-loaded, the downstream usage note follows, and the raw HTTP path is appended compactly. No sentence is redundant.

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, parameter-light read with no output schema, the description supplies enough: what entities come back, what identifiers they carry, and how those identifiers are consumed elsewhere. Only the shape of the returned objects beyond id/name is left unspecified.

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 optional `fields` parameter is fully documented in the schema (100% coverage, including the ["*"] wildcard and size-saving advice). The description adds nothing about it, so the baseline 3 applies since the schema carries the burden.

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 (list MLSs approved for display on the account) and names what is returned (IDX ids such as a001 and names), which an agent cannot infer from the name alone. It also positions itself relative to the other MLS tools, though it does not name a specific sibling it could be confused with.

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?

"Use the id in the other MLS tools" gives a clear downstream usage instruction that tells the agent this is a prerequisite/feeder call for the MLS-related siblings. There are no explicit exclusions or negative conditions, which keeps it below 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=true, destructiveHint=false and openWorldHint=true, so safety is covered; the description adds the meaningful scoping constraint that data is limited to the caller's own account and includes the underlying endpoint path. It says nothing about pagination behavior, default result volume, or rate limits, keeping it short of 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?

Three short sentences with the scope restriction front-loaded ahead of the endpoint path. The trailing 'GET /clients/featured' is minimally useful developer context rather than padding, but it is the least load-bearing 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?

No output schema exists, and the description compensates by enumerating returned fields (address, price, status, photos, agent). With all 7 parameters fully documented in the schema and safety covered by annotations, the remaining gap is only the absence of any hint about default result size or time-window behavior.

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% across all 7 parameters, so limit/offset/fields/interval/date_type/start_datetime are already fully documented in the schema. The description adds no parameter meaning beyond the returned-field list, which matches the baseline 3 for schema-covered tools.

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 a specific verb and resource (featured/active listings) and enumerates the returned attributes (address, price, status, photos, agent). The 'only the account's own listings, never general MLS data' clause separates it from MLS-wide siblings, though it does not name 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?

The scope statement implies when this tool applies (account's own featured listings), but there is no explicit when-to-use guidance versus idx_list_off_market_listings, idx_list_sold_pending_listings, or idx_list_supplemental_listings, nor any note on prerequisites such as account type.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds useful context by naming the underlying GET endpoint and the single-note variant, but does not disclose pagination, rate limits, or output shape.

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

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

Two short sentences, front-loaded with the tool's purpose and the key note_id condition. There is no filler, and the endpoint reference adds concrete context without bloat.

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 annotations, 100% schema coverage, and lack of an output schema, the description provides enough for correct invocation. It could say more about the returned note structure or pagination, but for a read-only notes listing it is largely 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 parameters, including note_id and fields. The description restates the note_id behavior but adds no syntax or semantic detail beyond what the schema provides.

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 resource (lead notes) and the two modes: all notes for a lead, or one note when note_id is provided. It does not explicitly contrast with siblings like idx_add_lead_note, but the retrieval purpose is 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 note_id conditional, which tells the agent how to switch between listing and fetching a single note. However, it does not state when to use this versus idx_get_lead or idx_add_lead_note, nor does it give exclusions or prerequisites.

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 and non-destructive, and the description still adds real behavioral facts: a 500-lead per-reply cap, offset-based paging with pagination info in the reply, and that each call draws on the key's hourly API quota. It also discloses the underlying GET /leads/lead endpoint, which matters for open-world rate-limited APIs.

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 sentences, each carrying distinct load: payload contents, page-size limit and paging, filtering options, and cost. The most decision-relevant facts (what you get, how big, what it costs) come first with no filler.

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 return-value burden and does so by enumerating the returned field groups and the 500-item page size with paging pointer. Safety is covered by annotations, cost by the quota note, and filtering by the date-window sentence, leaving nothing essential for a correct call 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 six parameters including the date_type enum and interval bounds are already documented, making 3 the baseline. The description only loosely reinforces that a time window applies to signup, edit, login, or activity dates and that offset pages; it adds no format 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 names a specific verb and resource ('List the account's leads') and defines the resource precisely as website registrants, plus the fields returned. That scope is enough to separate it from idx_get_lead (single record) and from the per-lead listers such as idx_list_lead_searches without opening a 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 concrete usage context: filter with a time window on one of four date bases, page with offset when a reply exceeds 500 leads, and expect it to consume an hourly API access. It does not explicitly say when to prefer this over idx_get_lead or idx_list_lead_searches, so no exclusions or alternatives are stated.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the REST endpoint string and does not disclose the default time window, date_type filtering behavior, or pagination/return shape — the actual behavior an agent must anticipate.

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

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

Two short sentences, front-loaded with the resource and the key conditional. Nothing is wasted, but the brevity comes partly at the cost of substance rather than purely from efficiency.

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 six parameters including a constrained interval window and a date_type enum, and no output schema, the description should explain the default time window and what a returned property record looks like. It does none of that, leaving the agent to rely entirely on schema prose.

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 every parameter (interval, date_type, fields, start_datetime, property_id) is already documented in the schema. The description merely restates the property_id behavior that the schema already explains, adding no extra meaning; 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?

States a specific verb+resource ('Properties a lead saved') and notes the single-item mode when property_id is passed. It is clearly distinct from siblings like idx_list_lead_searches or idx_list_lead_notes by virtue of the 'saved properties' resource, though it does not name 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?

The parenthetical '(or one when property_id is given)' gives minimal selection guidance between the list and single-item forms. There is no statement about when to prefer this over other lead-related listing tools or any preconditions.

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, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds that each search includes its results URL, which is useful, but says nothing about pagination, result limits, or what happens with empty results.

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 tight sentence plus the endpoint template; no wasted words. The endpoint path is arguably redundant with the description but aids the agent in understanding scope.

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 list endpoint with fully described parameters and annotations carrying the safety profile, the description covers the essentials and clarifies the return payload ('results URL of each'). Only routing to related siblings is thin.

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 fully documents lead_id, search_id, fields, interval, date_type, and start_datetime. The description only adds the lead_id/search_id relationship and return data, which slightly reinforces the schema rather than supplementing 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 and resource ('Saved property searches of a lead') and clarifies the single-search variant when search_id is supplied. It is distinguishable from idx_list_leads and reasonably from idx_list_lead_saved_properties, though it never explicitly names those 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 parenthetical '(or one search when search_id is given)' implies usage for single vs. all searches, but there is no explicit when-to-use guidance, prerequisites, or named alternatives such as idx_get_lead or idx_list_lead_saved_properties.

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, openWorldHint, and non-destructive behavior, so the description is not responsible for the safety profile. It adds useful behavioral context by stating that results include ids and occurrence counts and by specifying the GET path, though it does not discuss pagination or rate limits.

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 compact and front-loads the resource scope before listing filter-field mappings and the endpoint. Every sentence contributes useful information with no filler.

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, schema-complete listing tool with annotations covering safety, the description is largely complete. It explains the returned data and filter mappings, though it could mention prerequisites such as deriving idx_id from idx_list_approved_mls, which is only covered in the schema.

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

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

Schema coverage is 100%, so parameter basics are already documented. The description adds meaningful semantics by mapping which filter fields are valid for cities, counties, and postalcodes, which goes beyond the schema's broader note that filter_field must fit kind.

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 resource as cities, counties, or postal codes present in an MLS's data, and notes the ids and occurrence counts returned. It is distinguishable from siblings like idx_list_mls_property_types and idx_list_mls_search_fields by resource type, though it does not explicitly name alternatives.

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

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

The description explains what data is available and maps filter fields to each kind, but it gives no explicit guidance on when to choose this tool over siblings or what prerequisites apply. Usage must be inferred from the purpose rather than stated.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value by disclosing the shape of each returned record (IDX type id, MLS name, parent type, subtypes), which matters because there is no output schema, but it says nothing about filtering behavior, result volume, or pagination.

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

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

Two short fragments with no filler; the returned-field list is front-loaded. However, the second half is a bare endpoint path that largely duplicates the tool's identity rather than adding guidance.

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 does the minimum by naming the returned properties, which is genuinely useful. It is still incomplete for an openWorld read tool with filter parameters: no indication of whether results are flat or nested (parent/subtype relationships implied but unstated) and no note on how filtering narrows the list.

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, including the enum for filter_field and the rf/'*' semantics of fields. The description only restates idx_id implicitly and adds nothing about the filter_field/filter_value pairing, so baseline 3 applies.

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

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

The description names the resource ('Property types of an MLS') and enumerates what the record contains (IDX type id, MLS name, parent type, subtypes), but it is a noun phrase with no verb, leaving the agent to infer that this is a list/retrieval operation. It is distinguishable from siblings like idx_list_mls_locations by resource, though the trailing endpoint path does more differentiating work than the prose.

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 statement of when to use this tool versus idx_list_approved_mls, idx_list_mls_search_fields, or idx_list_mls_locations, and no mention of prerequisites beyond the schema's parenthetical reference to idx_list_approved_mls. Usage must be inferred entirely from the name and the endpoint path.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the shape of what is returned (field name, display name, property types) and the REST path, which is genuinely useful since there is no output schema, but it says nothing about filtering behavior or result size.

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 compact sentences, front-loaded with the resource definition before the endpoint reference. Nothing is padded, though the trailing raw path is marginal value for an agent.

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 list tool against a fully documented 4-param schema with annotations covering safety, the description plus structured fields are sufficient. The missing piece is sibling differentiation, but nothing required to invoke the tool correctly is absent.

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%, including the idx_id example, the fields wildcard behavior and the enum for filter_field. The description adds no parameter information beyond the schema, so 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?

States a specific verb and resource: lists searchable MLS fields with field name, display name and property types. It's clear what the tool does, but it never distinguishes itself from close siblings like idx_list_mls_property_types or idx_list_mls_locations, which an agent could easily confuse it with.

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

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

There is no when-to-use guidance at all: no statement about when this is needed versus idx_list_mls_property_types, and no mention that idx_id must first be obtained from idx_list_approved_mls (that hint lives only in the schema). The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds the account scope and REST endpoint, but says nothing about pagination, result volume, or what happens when the interval window is large – useful additions but not rich behavioral context.

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

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

Three short fragments with zero filler, and the resource scope is front-loaded before the filtering note and endpoint. The telegraphic style loses a little clarity (no explicit verb) 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 should hint at what a call returns (a list of office records shaped by the fields parameter), which it does not. For a read-only list tool with fully described parameters and annotations, it is adequate but leaves the return shape and filtering edge cases to inference.

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 all six parameters are already documented in the input schema, making 3 the baseline. The description adds one genuinely new constraint – that filtering is either by a single field or by a time window – which resolves an ambiguity the schema does not state, but it provides no other syntax or format detail.

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

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

The description names the resource (offices on a multi-user IDX Broker account) and the underlying endpoint GET /clients/offices, which disambiguates it from siblings such as idx_list_agents or idx_list_mls_locations. The verb is only implied – the title carries 'List' – so it is clear but not stated in the description itself.

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 mentions two filter modes ('by one field or by a time window') but never says when to use this tool versus alternatives, what prerequisites exist (e.g. multi-user account requirement), or what happens with no filters. No exclusions or sibling routing are given.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds essentially nothing beyond the endpoint path—no mention of pagination behavior, time-window semantics, or response characteristics.

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 is front-loaded with the resource. It is efficient, though the endpoint reference is of limited value to an agent and the extreme terseness leaves important context unstated.

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 tool with seven optional parameters, time-window filtering, and no output schema, the description is incomplete. It does not explain what an off-market listing is, how the interval/date_type parameters shape results, or what to expect in the response.

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 seven parameters are documented in the schema. The description adds no additional meaning beyond the structured parameter docs, making the baseline 3 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 identifies the resource as the account's off-market listings, which is clearer than the bare tool name. However, it does not differentiate this from sibling listing tools like featured, sold/pending, or supplemental listings, and 'GET /clients/offmarket' is an endpoint reference rather than a purpose explanation.

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

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

There is no guidance on when to use this tool versus idx_list_featured_listings, idx_list_sold_pending_listings, or idx_list_supplemental_listings. The description gives no context, exclusions, or selection criteria.

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, destructiveHint=false and openWorldHint=true, so the safety profile is carried. The description adds the response shape (id, name, URL) and the underlying endpoint, which is genuinely useful with no output schema, but says nothing about pagination limits, ordering, or how interval/start_datetime affect a static saved-link list.

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 compact fragments with zero filler; the resource definition and returned fields come first. The trailing 'GET /clients/savedlinks' is mildly redundant with the tool name but still informative for agents mapping to the REST API.

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-required-param list tool with no output schema, listing the returned fields is a meaningful compensation. However, the presence of interval/start_datetime parameters on what looks like a static resource is unexplained, and there is no note on default page size or empty-result behavior.

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 documented in the schema itself, setting the baseline at 3. The description contributes nothing extra about limit/offset/fields/interval, and notably does not explain why a time-interval parameter applies to saved links.

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 (list) and resource (saved links) and even explains the domain concept (pre-built property search pages) plus the fields returned (id, name, URL). It stops short of distinguishing itself from adjacent siblings such as idx_list_system_links or idx_get_saved_link_count.

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 no when-to-use guidance, no prerequisites, and no mention of alternatives among the 25 siblings. An agent must infer from the name alone that this is the bulk-listing counterpart to idx_get_saved_link_count.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds the useful scope detail that these are listings removed from the MLS feed, but says nothing about pagination, default time windows, or response behavior beyond the endpoint path.

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 with the core resource meaning front-loaded. The trailing 'GET /clients/soldpending' is somewhat technical but still compact and potentially useful for API mapping.

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?

Parameter details are fully covered by the schema, but with no output schema and a relatively rich seven-parameter tool, the description gives no sense of default behavior, time-window semantics, or what a response contains. It is minimally adequate rather than 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 100%, so all seven parameters are fully documented in the schema itself. The description adds no parameter meaning beyond the endpoint path, which is appropriate but leaves it at the baseline for schema-covered parameters.

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

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

The description states a specific resource ('The account's sold and pending listings') and clarifies it as listings 'removed from the MLS feed,' which distinguishes it from active-listing siblings. It does not explicitly name the closest sibling, idx_list_off_market_listings, but the purpose is immediately clear.

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 definition of sold/pending as removed from the MLS feed, but there is no explicit guidance on when to use this versus idx_list_off_market_listings or other listing-list tools. No exclusions or alternatives are mentioned.

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/openWorld/non-destructive, so the safety profile is covered. The description adds two useful facts beyond that: results are scoped to the calling account ('the account's') and the default payload is a limited field set. It says nothing about pagination behavior, default time window, or ordering, which matter for a 7-parameter list endpoint.

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

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

Two short sentences, front-loaded with the resource and its distinguishing qualifier, with zero filler. The trailing 'GET /clients/supplemental' is marginal value but harmless.

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?

A read-only list with fully documented params and no output schema needs little, and the description covers scope and default field set. However, it omits result shape, pagination/limit behavior, and what supplemental records actually contain, leaving an agent to guess at return structure.

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 every parameter is already documented with defaults, ranges, and the rf/['*'] convention. The description's 'basic set of fields' loosely echoes the fields parameter but adds no syntax or interaction detail. 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?

States a specific verb and resource and qualifies the resource as 'supplemental (non-MLS)', which materially separates it from idx_list_featured_listings, idx_list_off_market_listings, and idx_list_sold_pending_listings. It does not explicitly name those siblings, but the '(non-MLS)' qualifier does the core differentiating work.

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

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

There is no guidance on when to pick this tool over the other listing listers in the sibling set, and no prerequisites or exclusions. The agent must infer selection purely from the word 'supplemental'.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint (GET /clients/systemlinks) and enumerates the returned attributes, but says nothing about permissions, rate limits or result size beyond the fields parameter.

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 compact sentence that front-loads the resource and its returned attributes, plus the endpoint as a trailing detail. Slightly fragment-like grammar, but no wasted content.

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 list tool with full annotation coverage and complete parameter documentation, the description supplies the essentials: what the items are, what attributes come back, and that they are directly linkable. Nothing critical is missing.

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

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

There is one optional parameter with 100% schema description coverage, so the schema already explains the field-filtering behavior and its API-size tradeoff. The description adds nothing further about it, making the baseline 3 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 names a specific resource — the account site's system pages — and gives concrete examples (search, featured, contact) plus the returned fields (name, id, URL). That is enough to tell it apart from data-listing siblings like idx_list_saved_links or idx_list_featured_listings, though no sibling is named 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 phrase 'which can be linked to directly' hints at the use case (building navigation/deep links to built-in pages), but there is no explicit when-to-use or when-not guidance and no alternative tool is mentioned.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that this is an account-level GET listing with specific fields, which is useful context but does not add deeper behavioral details like auth or rate limits.

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 very short and front-loads the resource and returned fields. The second fragment naming the HTTP endpoint is slightly implementation-oriented, but overall the definition avoids waste.

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 list tool with full parameter schema coverage and clear annotations, the description is complete enough to call correctly. It states the resource and returned fields; only sibling differentiation and richer usage guidance are missing.

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

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

Schema description coverage is 100%, so limit, offset, and fields are already well documented in the input schema. The description's mention of id, name, URL, and options gives some sense of available fields, but it does not materially expand on parameter semantics 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 identifies the resource (JavaScript widgets on the account), the returned fields (id, name, URL, options), and the underlying endpoint. It is clear what the tool does, though it does not explicitly differentiate itself from the sibling idx_get_widget.

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 no guidance about when to use this tool instead of alternatives such as idx_get_widget. It only states what the resource is, leaving usage decisions to inference from the tool name.

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

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

The annotations already disclose that this is a non-read-only, destructive, idempotent operation. The description adds useful behavioral detail beyond that: given values replace stored values, only changed fields should be passed, and field names come from idx_get_lead. It does not cover permissions, error behavior, or response semantics, but it meaningfully supplements 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 front-loaded with 'WRITE' and then efficiently covers replacement semantics, minimal-field guidance, naming source, and endpoint. Every clause carries actionable meaning with no filler.

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 mutation with a nested fields object and no output schema, the description supplies the key operational details: existing lead, replacement behavior, minimal field passing, and field-name source. It could be stronger by explicitly stating that omitted fields remain unchanged and by mentioning response or error behavior, but it is largely 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%, so the baseline is 3. The description adds real value by explaining that field keys are IDX lead field names as returned by idx_get_lead and by giving examples such as firstName, lastName, email, phone, and status, which clarifies the nested fields object beyond the schema's minimal wording.

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

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

The description states a specific verb and resource: updates fields of an existing lead. It clearly distinguishes the operation from creation by specifying 'existing lead' and 'WRITE', so an agent can identify it without opening sibling schemas.

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 usage context by saying to update an existing lead and to 'only pass what must change', which helps avoid unnecessary overwrites. It also points to idx_get_lead for field names, though it does not explicitly name alternatives or when-not-to-use cases.

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