Taco Street Locating

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

Adds substantial behavior beyond the annotations: reply timing (Central Time business hours, usually within a few hours), rate limiting, the point-in-time nature of answers, and the warning that agent sessions end so polling alone can strand an answer. This is exactly the operational context annotations can't 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-loaded with the core purpose, then escalates to the critical contact/consent guidance and rate-limit note. Dense but every clause carries information; the parenthetical about sessions ending is slightly verbose but 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?

An output schema exists so return values needn't be explained, yet the description still flags the question_id channel. Combined with timing, rate limits, and consent guidance, an agent has everything needed to invoke this 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 five parameters. The description reinforces the consent requirement for contact and that specifics beat generalities for question, but adds no syntax or format detail beyond the schema — 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 (ask a question to a human locator) and sharply scopes it with 'only a human can answer', plus concrete example questions. It also implicitly distinguishes itself from the polling sibling by noting it returns a question_id for check_answer.

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 clear context for when to use it (real-time, human-only facts like current specials and availability) and operational guidance (batch related questions, rate limited, contact strongly recommended). It does not explicitly state when NOT to use it or name request_locator_help as an alternative, 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that this is a polling operation (implying the answer may not be immediately available), which is useful context, but it does not disclose pending/failed states or retry expectations — the key behavioral detail for a poll tool.

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

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

A single front-loaded sentence with no filler; the action, resource, and keying parameter all appear immediately.

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 not be explained, and the one parameter is covered. However, for a polling tool the description omits the behavior an agent most needs — what to do while the answer is unavailable — leaving a meaningful 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?

Schema description coverage is 100% and the single parameter is fully documented in the schema as the id returned by ask_a_locator. The description's 'by question_id' adds no syntax or format 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 (poll/check) and resource (the answer to an ask_a_locator question) keyed by question_id, and explicitly ties itself to the ask_a_locator sibling as the source of the id. Clear enough to distinguish from the sibling, though it doesn't contrast against other polling-style 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?

Use of the word 'Poll' implies this is called after ask_a_locator and may need repeating until an answer exists, but the description never states when to call it, how often, or when to stop. Usage is implied rather than guided.

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

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

Annotations cover the safety profile (write, non-idempotent, non-destructive, closed-world), so the bar is lower. The description adds real value beyond them: it discloses that buildings are appended to the renter's persistent saved list and that the return is a shareable /my-list?s=... URL with compare/AI Read/tour features. It doesn't warn about duplicate entries on repeat calls despite idempotentHint=false.

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

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

Two sentences, front-loaded with the core action and output, followed by the critical naming constraint. Slightly padded by the feature list ('compare, AI Read, and free tour requests'), which is marketing color rather than calling 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?

An output schema exists, so the return value needn't be explained, and the description still usefully characterizes the returned link. It covers the write effect (buildings added to a saved list) and input sourcing; only edge cases like duplicate handling or the 10-item cap (already in schema) are left implicit.

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 all three parameters, making 3 the baseline. The description's 'Use the EXACT names returned by search_apartments' reinforces the apartment_names semantics but largely restates the schema's own wording, adding no new 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 a specific action (turn finalist apartments into a shareable link) and a specific resource (Taco Street shortlist at /my-list), and explicitly ties it to the sibling search_apartments as its input source. An agent can distinguish this from search_apartments and get_apartment_details without opening 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?

'Turn finalist apartments into...' clearly implies this is the post-search step, used once a renter has narrowed candidates, and tells the agent to pull names from search_apartments. It gives a clear usage context but states no exclusions, no limit/duplication caveats, and no explicit when-not-to-use guidance.

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

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

Annotations already cover the safe-read profile (readOnly, idempotent, non-destructive), but the description adds freshness semantics neither the annotations nor schema carry: specials are 'last-known (dated — treat as last-known, not current)' and totals must be computed by the caller. That staleness caveat is exactly the kind of beyond-structured-fields disclosure that prevents an agent from misreporting data as live.

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

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

A single dense block with the payload front-loaded, then the input rule, then the computation/verification caveat. No filler sentences; every clause carries operational information.

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

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

With an output schema present, return values need no explanation, and the description still supplies the data-freshness framing the schema omits. It is complete for a two-parameter read tool, only omitting any note on what happens when a building name is ambiguous or unmatched.

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

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

Schema description coverage is 100%, so both parameters (name, city enum) are already documented in the schema, and the enum for city is self-explanatory. The description's 'EXACT name' instruction largely restates the schema's own 'Exact building name from search_apartments', so it adds little beyond the baseline.

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

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

States a specific verb+resource ('Full fact sheet for one building') and enumerates the payload: floorplan pricing with as-of dates, move-in cost components, dated specials, amenities, walkability, virtual tour. It explicitly distinguishes itself from the sibling search_apartments by naming it as the source of the required name.

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 EXACT name from search_apartments' tells the agent both the prerequisite and which sibling produces the input. 'Compute totals yourself from components; a free human locator confirms live numbers' routes the agent away from expecting live pricing here and toward ask_a_locator for confirmation, though it never states a when-not-to-use case.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds value by stating that no draft, contact details, or internal notes are returned, and includes a security instruction about not sharing the key publicly. This goes beyond the annotations and provides useful 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?

The description is two sentences with no wasted words. The primary purpose is stated first, followed by exclusions and a security note. It is front-loaded and highly efficient.

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

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

Given the tool's simplicity (2 params, output schema present, annotations cover safety), the description provides all necessary context: what it does, when to use it, what it excludes, and a security warning. Nothing critical is missing for an agent 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 both parameters (request_id and request_key) are fully described in the schema. The description only restates the purpose of the key ('private request key') without adding new semantic meaning. Baseline 3 is appropriate when the schema carries the parameter documentation.

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

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

The description clearly states the tool retrieves progress and, after approval, a reviewed report snapshot using a private key. It explicitly lists what is not returned, distinguishing it from other research-related tools. This is specific and 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?

The description provides clear context: use when you have a private request key and after Alexander approves. It implies the tool is for continuing an existing research request, but it does not explicitly contrast with sibling tools like request_apartment_research. The condition 'after Alexander approves' gives a usage hint, though no exclusions 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 only declare readOnly=false, destructive=false, idempotent=true, openWorld=false; the description adds genuinely new context: asynchronous human-in-the-loop flow (staff acceptance, VA gap verification, Alexander's judgment), no email being sent, no guaranteed completion time, and a private continuation link. It is consistent with the annotations and does not contradict them, though it does not discuss rate limits or permission/consent failure modes beyond mentioning consent.

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, with the core action front-loaded and the workflow/return/exclusions following in a logical order. The trailing negative-sentence ('No immediate report, guaranteed completion time, or tour booking') is dense but earns its place; 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 and full schema description coverage, the description need not explain return payloads, and it still flags the continuation link. Combined with the annotations, an agent has enough to call this 15-parameter tool correctly, though the explicit sibling routing and retry semantics remain implicit.

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 15 parameters are each documented in-schema (including the request_key idempotency rule and shortlist_token origin), so the schema carries the load. The description adds essentially no parameter-level detail beyond the 'with consent' framing, 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 opening sentence states a specific verb and resource — 'Submit a saved shortlist and renter brief' — so the agent knows exactly what is being created. It also differentiates from the tour sibling by declaring 'No ... tour booking', and it names the concrete outcome ('private continuation link'). This is well beyond a restatement of the name/title.

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

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

The description implies when this applies (a paid-research request that requires staff acceptance, with no immediate report) and rules out tour booking, but it never explicitly says 'use request_research_tours instead for tours' or states prerequisites like needing a prior create_shortlist. Usage is inferable but not spelled out against the sibling set.

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 mark this as a non-read-only, idempotent, non-destructive, closed-world write; the description adds real context beyond that — it's free (properties pay locators), follow-up arrives by text/email rather than a cold call, and duplicate submissions within 24h return the existing lead, which directly explains the idempotentHint. Consent and real-contact requirements are also disclosed.

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

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

Three tight sentences, front-loaded with the core action and actor, then funding model, contact channel, and dedup rule. Every sentence carries information the agent needs; nothing 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?

Output schema exists, so return-value detail isn't required, and the description still covers the one non-obvious return behavior (duplicate returns the existing lead). Consent requirements, cost, follow-up channel, and the actor are all addressed, leaving no gap for an agent deciding whether to call this.

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 per-field descriptions for all nine parameters, so the baseline is 3. The description reinforces the critical 'contact' requirement (real phone or email, with consent) but adds no format or syntax detail beyond what the schema already states.

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

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

The description names a concrete verb and resource — handing a renter to a named human locator who confirms live pricing/availability and books tours — so the agent knows exactly what the call accomplishes. It does not explicitly distinguish itself from the sibling ask_a_locator, which is the main thing keeping this from 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?

It gives clear usage conditions: requires the renter's real phone/email shared with consent, one request per renter, and duplicates within 24h return the existing lead. What's missing is an explicit when-not or a named alternative (e.g. ask_a_locator) for cases where a request has already been made.

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 idempotentHint=true but the description adds concrete behavioral detail: 'identical retries return the existing request, changed preferences require staff follow-up.' It also clarifies side effects with 'No appointment is booked or message sent' and notes the private key/contact usage. This goes well beyond the structured 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 the purpose and precondition, then packs behavioral constraints into compact sentences. The line about preferred_times is mildly redundant with the schema, but every other sentence adds distinct value and the overall length is appropriate.

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 four required parameters, an output schema, and annotations, the description covers preconditions, idempotency, side effects, contact/key usage, and the handoff limit. Nothing an agent needs to avoid misinvocation is missing; the only omitted details are already covered by the output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description's 'Include preferred dates, times and timezone in preferred_times' largely echoes the schema's parameter description. No additional semantic meaning is added beyond what the schema already documents.

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: 'request human tour coordination for selected apartments.' Adds scoping conditions 'After report approval and explicit renter consent' and 'Uses the existing private research key and contact,' which clearly separates this from sibling request_apartment_research without needing 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?

Provides clear context: 'After report approval and explicit renter consent' states when this tool is valid, and 'One handoff per research report' sets an important boundary. It does not explicitly name alternatives or exclusions, but the prerequisites are strong enough to guide selection.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is fully covered structurally. The description adds a light behavioral detail (scored matches with starting prices and a 'why' per building) and the long-term-rental restriction, but nothing about pagination, ranking logic, or empty-result behavior.

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

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

Two tight sentences, zero filler, with the scope (cities) front-loaded and the use restriction trailing as a qualifier. Every clause carries information.

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

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

With an output schema present, the description needn't explain return shape, and it still summarizes what comes back. It covers scope, output flavor, and the rental-type restriction, but stops short of any guidance on when to escalate to detail or research siblings.

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 the city enum, limit bounds, and a plain-language query example all documented in the schema itself. The description adds no syntax or format guidance beyond that, so the baseline of 3 applies.

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

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

States a specific verb (Search) and resource (Taco Street's curated apartment inventory), and pins the scope to four named metros. It clearly reads as a discovery/search tool, though it never names a sibling like get_apartment_details to draw the boundary 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?

'Use for long-term rentals only' gives a real inclusion constraint, narrowing the tool to a rental use case. However, it does not name alternatives (e.g., get_apartment_details, request_apartment_research) or say when this tool is the wrong choice for a given intent.

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