listing

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is known. The description adds genuinely useful context beyond them: no account or prop_id is required (auth-free), and it discloses the semantic of the response field ('is_active: true means covered'). It stops short of noting latency/caching or what a false/error response looks like.

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?

Roughly three short sentences, front-loaded with the discovery-stage framing and endpoint, with zero filler. Every sentence (identity, prerequisites, usage gate) 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?

For a one-parameter, read-only coverage check with an output schema present, the description supplies everything the agent needs: purpose, prerequisites, usage gate, and the interpretation of the key response field. Nothing material 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% and the single 'state' parameter is fully documented (short code or full name) in the schema. The description only reinforces that no account or prop_id is needed rather than adding new parameter semantics, so the baseline 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 ('is this state served by beycome MLS?') and even names the underlying endpoint (GET /mls/is-covered). It is clearly distinct from the sibling tools (comps, estimate, listings, messages), so an agent can route 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?

Explicitly prescribes the workflow position ('Use before listing to confirm beycome operates in the property's state') and states the negative case ('If not covered, the listing flow does not apply'). Both when-to-use and when-not-to-use are covered.

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 declare readOnlyHint and openWorldHint. The description adds genuinely non-obvious behavior: the endpoint can take ~1 minute on a cold query, timeouts are safe to retry, no account or prop_id is required, and photo/listing-link fields are stripped to shrink the response. This is exactly the extra context annotations cannot carry.

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?

Purpose is front-loaded, followed by filters, usage routing, and behavioral caveats in short scannable lines. The retry advice is slightly conversational but each sentence conveys actionable information; nothing 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?

With an output schema present, return shape needn't be explained, and the description still notes which fields are stripped. For a 13-param read-only discovery tool it covers purpose, routing, latency, and auth prerequisites without gaps.

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

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

Schema description coverage is 100%, so all 13 parameters are already documented, including the property_type enum values. The description only summarizes filter categories (price/beds/baths/area/lot/type), which mirrors the schema rather than adding 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 — sold comparable listings near a location — and even names the underlying endpoint (GET /comps). It distinguishes itself from siblings by naming beycome_estimate as the companion tool, so an agent can place it 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?

"Use during discovery to support pricing alongside `beycome_estimate`" gives clear context and names a related tool. It does not state when to prefer one over the other (exclusions), so it stops 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=true and openWorldHint=true, so safety is covered. The description adds genuine non-obvious context: 'No account or prop_id needed' clarifies the auth/session requirement, and it names the pricing strategies returned (fast / balanced / max). It stops short of detailing latency, coverage limits, or failure modes for an open-world address lookup.

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 tight paragraphs, front-loaded with the discovery-stage positioning, then the return contents, then routing. Every sentence carries distinct information with no repetition of the title or annotations.

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 two-parameter estimation tool with an output schema and safety annotations, the description covers stage, inputs needed, return shape, and sibling routing. Nothing an agent needs 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 description coverage is 100%, and the schema already spells out the address format, ZIP requirement, and the unit-vs-embedded-unit preference in more detail than the description does. The description adds no parameter-level meaning beyond the incidental 'no prop_id needed' note, 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 — estimate a property's SALE value — and names the two underlying sources (beycome CMA + Zillow Zestimate). It explicitly contrasts with the sibling rental tool and the comps tool, so an agent can distinguish it 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?

Gives explicit when-to-use ('Use during discovery to set a list price'), a pairing recommendation ('pair with beycome_comps'), and a named alternative for the adjacent case ('For rental inquiries, use beycome_rental_estimate instead'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real operational context beyond that: it is token-scoped, a RESO list endpoint on the normal api base, and the newly created listing is 'typically the newest entry'. It stops short of pagination or rate-limit detail, but with annotations carrying the safety burden a 4 is warranted.

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

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

Front-loads the stage and endpoint, then uses two tight bullets for the main uses. The workflow routing detail earns its place, though the markdown-heavy formatting and stage framing are slightly more verbose 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?

With an output schema present, return values need not be explained, and the description fully covers endpoint, auth scoping, and routing to sibling tools. Nothing an agent needs to call and place this tool 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% with a single access_token parameter fully documented in the schema, so the baseline is 3. The description's 'token-scoped' note aligns with but does not extend the schema's own token description.

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 ('the signed-in user's properties (GET /properties)') and immediately distinguishes itself from siblings by naming the exact downstream tools it feeds (beycome_questionnaire_link, beycome_messages, beycome_showings, beycome_offers). An agent can tell what this does and where it sits in the workflow 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?

Explicitly enumerates two use cases: post-submit-property recovery and as the entry point for a returning user referencing 'my listing' without an id. It even maps resulting status to the correct next tool, giving concrete when-to-use and branching logic.

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 cover readOnlyHint/openWorldHint, and the description adds real operational context: 401 means an invalid/expired token, the list is deliberately unpaginated because upstream ``page`` is overloaded, soft-deleted rows shrink a page without being an error, and the payload is a bare array under ``data``. That is well beyond the annotations, though it stops short of describing ordering guarantees 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?

Front-loads the stage and method, then splits the two modes into clearly labeled bullets, followed by quirks and error handling. Despite its length, nearly every sentence carries a distinct operational fact (unread flag, message_type semantics, soft-delete behavior, payload shape).

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 read tool with an output schema, the description covers the remaining gaps an agent needs: mode selection, row fields, unread semantics, the pagination quirk, error handling, and the next tool to call. Nothing material 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 both parameters are already documented; baseline is 3. The description still adds meaning: it explains that ``thread`` should come from a list row to open one conversation, and that the upstream page parameter is intentionally withheld. It adds workflow context the schema alone does not convey.

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 (read) and resource (the owner's buyer/inquiry messages) and pins the lifecycle stage (post-publish) plus the underlying GET /messages. The two-mode structure (list vs. single thread) is spelled out, so an agent can distinguish it from siblings like beycome_reply_message.

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 omit ``thread`` (list ~20 recent conversations) versus when to pass it (drill into one full conversation using a thread value from a list row). It also routes the agent elsewhere for the follow-up action ('To answer a message, use beycome_reply_message') and names the re-auth path for 401s.

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 cover readOnlyHint and openWorldHint; the description adds meaningful behavior beyond them: an access_token is required, results are paginated at 20 per page, each entry is a full offer record with listed fields, and there is no server-side prop_id filter. The 'Read-only.' sentence is the one part that restates the annotation.

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?

Content is front-loaded with the lifecycle stage, then auth, return shape, and constraints; nearly every sentence earns its place. The standalone 'Read-only.' sentence is redundant with readOnlyHint rather than additive, a minor structural waste in an otherwise tight description.

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, read-only list tool with an output schema present, the description covers everything an agent needs: lifecycle timing, auth source, pagination mechanics, per-entry fields, and a filtering limitation plus the client-side workaround. Nothing material is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning by disclosing the page size (20 per page) and the need to pass page to advance, which the schema's 'Page number of the paginated offers list' does not convey. It does not add anything beyond the schema for access_token.

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 ('offers received on the owner's listings') and even pins the underlying endpoint (GET /offers). It distinguishes itself from siblings like beycome_get_my_listings by scoping to received offers, and from the messaging/response tools by stating that accept/reject/counter is not here.

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 states the lifecycle trigger ('used once a listing is live'), gives the operational workaround for single-listing views (no server-side prop_id filter, filter client-side on each offer's prop_id), and explicitly excludes an adjacent capability (responding to offers). When-to-use, how-to-adapt, and when-not are all present.

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 declare readOnly=false, openWorld=true, destructive=false. The description adds substantial extra context beyond that: the 7-day link expiry, that the tool only returns a URL with no login step, the browser-side workflow, the ~48h listing timeline, and explicit 401/403/422 failure semantics.

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?

Content is front-loaded (purpose and prerequisite first) and the numbered steps and failure-mode list make it scannable. It is somewhat long, but nearly every sentence adds operational value.

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 an output schema present, return values need not be explained, and the description fully covers prerequisites, next steps, timing, and error handling. Nothing needed to invoke 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 description coverage is 100%, so the schema already documents prop_id and access_token, and the description adds no parameter-level detail. 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?

The description gives a specific verb and resource ('mint a pre-authorized link to the MLS questionnaire form') and even names the endpoint. It is clearly distinguishable from siblings like beycome_submit_property_link, which it explicitly references.

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 states the prerequisite ('Requires a PAID listing (premium active, Flat/Yes)'), covers both triggering scenarios (just paid vs. already-paid with questionnaire pending), and routes to the related sibling beycome_submit_property_link. An agent knows exactly when this 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 cover read-only and open-world, but the description adds substantial context beyond them: no account or prop_id required, the exact endpoint, the returned fields, and a crucial caveat that unrecognized addresses still return success:true with a generic market rent and how to detect it. This is genuinely valuable behavioral disclosure.

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

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

Front-loads the discovery-stage purpose, then routes to siblings, then explains returns, then the caveat. Each sentence earns its place and nothing is 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?

With an output schema present the description needn't explain returns, yet it does so helpfully, and it supplies the critical reliability caveat. Nothing an agent needs to call this 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 description coverage is 100%, so the baseline is 3, but the description adds meaning by clarifying that a unit number signals a rental inquiry and that no prop_id is required. The address formatting detail is fully carried by the schema, so it stays just above baseline rather than at 5.

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 ('estimate a property's monthly RENT') and explicitly contrasts with the sibling 'beycome_estimate', which handles sale-price estimates. An agent can distinguish this tool from its closest sibling purely from the description.

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

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

Gives explicit when-to-use ('ONLY for rental inquiries or for properties that have a unit number') and when-not, naming the alternative ('For sale-price estimates, use beycome_estimate'). Routing is unambiguous.

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 declare readOnly=false, openWorld=true, destructive=false. The description goes well beyond them: it warns this is a live send with a real email notification queued, that sent text is final, and it enumerates concrete failure modes and their 400 messages plus the 401 re-auth path via `beycome_signin_start`/`beycome_signin_verify`.

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 verb/resource and endpoint, then organized into clear blocks (behavior, instructions, parameters, outcomes). It is longer than strictly necessary — the draft-polishing paragraph runs several sentences — but nearly every sentence carries actionable 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 mutation tool with an output schema present, the definition covers everything an agent needs: required params, recipient resolution, threading rules, success status (201 with data.id), and the error branches. Nothing material is left for the agent to guess.

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%, yet the description still adds real meaning: how to derive `to_user_id` (the counterparty, not the signed-in owner), why `subject` should be omitted on a thread reply (server prepends "Re: <original subject>"), and what a thread id is sourced from. This is meaning beyond literal field definitions.

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 ("reply to a buyer/inquiry message") plus the stage ("Post-publish stage") and the underlying endpoint (POST /messages/reply). It is clearly distinguished from the read-oriented sibling `beycome_messages`, which it explicitly names as the lookup tool for the recipient id.

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

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

Gives explicit when-to-use guidance (replying post-publish), the prerequisite lookup path (open the conversation in `beycome_messages` and take the non-owner participant id), and the threaded-vs-new split ("For a threaded reply pass the original thread verbatim and omit subject"). It also sets a behavioral policy: always polish the user's draft, never send it verbatim.

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?

Beyond the readOnly/openWorld annotations, the description discloses non-obvious behavior: the date range defaults to today → +90 days when omitted, and the response always mixes all event kinds with no server-side type filter, forcing the agent to filter client-side. That last point is exactly the kind of trait 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 the purpose, then usage stage, then parameter behavior, then the response caveat. Every sentence adds information an agent needs; nothing is redundant 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 an output schema present, return values need not be explained, yet the description still supplies the critical structural fact (the type field and its values) plus default/filter behavior. Nothing needed to invoke this 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 already 100% (formats and defaults are documented there), so the baseline is 3. The description goes further by adding the ordering constraint that to_date must be on or after from_date, which is not in the schema.

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

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

States a specific verb+resource combination — a calendar of showings, open houses, and offer deadlines — and even names the lifecycle stage ('post-publish'). An agent can distinguish this from sibling beycome_offers because the calendar explicitly mixes event kinds rather than being an offers list.

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?

'Used once a listing is live' gives clear context for when this tool applies. It does not, however, name an alternative tool or an explicit when-not condition, so it falls short of the routing guidance a 5 requires.

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?

Far exceeds the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true). It discloses that codes are dual-channel (email + SMS), valid 30 minutes, that re-running invalidates the previous code, explicit rate limits (5/min, 100/day), and the non-obvious fact that auth failures still return 2xx so the body envelope must be read instead of the status.

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 operation, then structured into response-case bullets and constraints. It is long, but nearly every sentence carries distinct operational value (error branches, rate limits, code lifetime), so only minor trimming is possible.

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?

Even though an output schema exists, the description supplies the response-interpretation rules the schema cannot convey (ok mirrors HTTP status, check data.success, 422 masked-primary hint). For a passwordless auth entry point with tricky 2xx-on-failure behavior, nothing an agent needs 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 description coverage is 100% for the single 'email' parameter, so the schema already documents it and the baseline of 3 applies. The description adds workflow context around the email (what happens if no account matches, or if it hits a secondary address) but no new syntax or format meaning for the parameter itself.

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

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

States a specific verb+resource ('send a one-time sign-in code') and immediately anchors it in the auth flow ('Account stage'), naming the sibling it pairs with (beycome_signin_verify) and the fallback (beycome_signup). An agent can distinguish it from every other sibling 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?

Gives explicit routing rules: run beycome_signup when 'Email not found.', exchange the code via beycome_signin_verify, and a hard 'never call it in a loop or as an automatic retry' exclusion. Both when-to-use and when-not-to-use are covered.

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 declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds substantial non-structured context: the token's location (data.data.access_token), its lifetime via expires_in, the 30-minute code expiry, rate-limited sends, and the critical error-semantics gotcha (HTTP 200 with success:false on invalid codes — check data.success, not the envelope's ok).

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?

It is long, but front-loaded with the core purpose and token location, then organized into clearly labeled blocks (IMPORTANT/persistence, next-step branching, error handling). Every section carries actionable information; only minor overlap between the persistence paragraph and the next-step list keeps it from a 5.

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 an authentication tool with an output schema present, the description goes beyond what is required: it explains the token path, persistence expectations across sessions/crons, and failure semantics. An agent has everything needed to call it correctly and handle both success and failure paths.

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

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

Schema description coverage is 100% for both parameters (code, email), so the schema already carries the parameter documentation and 3 is the baseline. The description adds only marginal parameter-adjacent detail (6-digit, one-time, 30-minute expiry), which is contextual rather than filling a schema gap.

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

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

States a specific verb+resource ('exchange the one-time code for the access_token') and even names the endpoint POST /auth/validate-code. It explicitly positions itself as the 'gateway to the listing flow' and distinguishes itself from the two siblings that send codes, beycome_signin_start and beycome_signup.

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

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

Gives explicit when-to-use (after beycome_signin_start or beycome_signup, with the 6-digit code), when-not (don't retry blindly on rate-limited sends; check memory for an existing token and only restart sign-in on a 401), and routes the agent to specific next-step siblings depending on account state.

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?

Beyond the annotations, it discloses the passwordless model, that registering auto-emails a 6-digit code, that signup doubles as signin-start, the HTTP 400 + errors-array failure format, and that no prop_id is needed. These are behaviors an agent cannot infer from readOnlyHint/openWorldHint alone.

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 stage label and endpoint are front-loaded and every sentence carries routing or behavioral information. It is slightly dense with parenthetical asides, but there is 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 an output schema present, return values need not be explained. The description supplies the account-flow context, follow-up tool, error handling, and required inputs, so an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all seven properties. The description only reinforces that firstname and phone are required and that prop_id is unnecessary; it adds little on is_owner, sms_unsubscribe, or the optional fields. Baseline 3 is appropriate.

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

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

The description names a specific verb and resource ("register a new beycome user") and even cites the endpoint (POST /auth/register), plus a lifecycle stage ("Account stage"). It is clearly distinguishable from the signin siblings it names.

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 states the trigger ("Use when the owner has no account yet"), the next step (beycome_signin_verify with the emailed code), an explicit exclusion ("do NOT call beycome_signin_start after signup"), and edge-case behavior (already-registered still sends a code). Nothing is left to inference.

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

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

Annotations declare readOnlyHint=false and openWorldHint=true but say nothing about lifespan or side effects; the description supplies the 7-day expiry, the fact that the actual listing creation happens in the browser with no login step, and the 401 failure mode. That is meaningful behavioral context beyond the structured hints, and it does not conflict with them.

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 stage and purpose, then organized into numbered user steps, prefill rules, failure modes, and follow-ups — easy to scan. It is on the long side and the package index mapping is repeated verbatim from the schema, which is the only notable redundancy.

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?

An output schema exists, so return values need no prose, and the description covers everything else an agent needs: auth prerequisite, user-scoping, expiry, conditional parameter use, failure handling, and the exact next calls to make. Nothing required to invoke this 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 baseline is 3, and the description adds real value on top: it tells the agent when to include vs omit package, and warns that the value is a page preset index rather than a payPremiumOpt reference — a distinction that is easy to get wrong. It also reinforces list_address as the address already discussed in chat.

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 artifact — 'mint a pre-authorized link to the submit-property page' — plus the concrete endpoint POST /api/mls/submit-property-link. It explicitly positions itself against siblings by naming beycome_signin_verify as a prerequisite and beycome_get_my_listings / beycome_questionnaire_link as the follow-ups, and clarifies that this tool only returns a URL rather than creating the listing.

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?

Explicit ordering ('Call AFTER signing in'), explicit conditional parameter rules ('ALWAYS pass list_address', 'Only pass package if the user has clearly chosen a tier in chat; otherwise omit it'), a stated failure mode (401 — bad/unverified token), and a named post-return sequence. The description also states there is no in-chat alternative, which forecloses the agent looking for another tool.

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