More than one roommate on your apartment buzzer number; settings decide who rings. Canada.
Scored across 20 tools
The consumer setup flow (check_building, create_setup, send_phone_code, confirm_phone_code, start_checkout, get_setup_status) and the partner flow are clearly distinct, and each tool maps to a specific step. A few partner tools (partner_get_links vs partner_list_sublinks, partner_get_stats vs partner_get_kit) are close in scope, but the descriptions do enough to separate them.
Nearly all tools follow a predictable snake_case verb_noun pattern (create_setup, send_phone_code, partner_get_stats, partner_rotate_key). The partner_* namespace prefix is applied consistently on one side and not the other, which is a minor asymmetry but still readable and predictable.
20 tools looks heavy at first glance, but the server serves two full workflows (a customer buzzer setup and a partner program with sublink management), and each tool appears to earn its place. Slightly over the ideal band but justifiable for the dual scope.
Both lifecycles are well covered: discovery, creation, phone verification, checkout, and status for customers; apply, verify, terms, key claim, links, stats, kit, sublink create/list/disable, payout, and key rotation for partners. Minor gaps exist (no way to cancel an abandoned setup or permanently delete a sublink), but agents can work around them.
Checks whether BuzzMeBro can give this building a local buzzer number, and returns the price, the free-trial terms and how the service works. Call this first. Stores nothing and costs nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| postal_code | Yes | The apartment building’s postal code, e.g. "M4B 1B3". Canadian postal codes only for now. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds value with "Stores nothing and costs nothing", which reassures the agent there are no side effects or billing consequences, plus a preview of the return contents. It does not cover auth or rate-limit behavior, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero filler, and the actionable sequencing instruction is front and center. Every clause earns its place by either stating the outcome or the return payload.
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 usefully enumerates what is returned (price, trial terms, how the service works), and it is complete for a single-parameter, side-effect-free check. An agent has everything needed to call it correctly and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single postal_code parameter is fully documented in the schema, including format and Canadian-only scope. The description adds no parameter-level meaning beyond that, 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 (checks) and resource (a building) and goes further to enumerate what the caller gets back: a buzzer number decision, price, free-trial terms, and how the service works. This is well beyond the title and clearly separable from the partner_* and *_phone_code 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?
"Call this first" gives explicit ordering guidance, which is exactly the kind of routing an agent needs in a multi-step onboarding flow. It does not name a specific alternative or state when-not to use it, so it stops short of a 5, but the sequencing instruction is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks the code the person read back to you. This proves the phone is theirs, which matters because that phone will open their front door. Five tries per setup. Next: start_checkout.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The digits from the BuzzMeBro text, e.g. "482913". | |
| setup_id | Yes | setup_id from create_setup. | |
| status_token | Yes | status_token from create_setup. Keep it private. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the state profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower, and the description still adds real context: the security consequence (the phone opens their front door) and a per-setup attempt limit. Nothing here contradicts the annotations; only the success/failure response shape is left 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?
Three short sentences, front-loaded with the action and immediately followed by the reason it matters and the flow pointer. The 'front door' clause is flavor but it does convey stakes efficiently; 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?
For a three-required-param, no-output-schema verification step, the description supplies what an agent needs: which code, the retry ceiling, and the next tool. Only the success/failure outcome (what a bad code returns, whether it consumes a try) is 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?
Schema description coverage is 100%, and each of the three parameters (code, setup_id, status_token) is documented in the schema itself. The description adds no syntax, format, or secret-handling detail beyond what is already there, 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?
Specific verb ('Checks the code') plus the concrete resource (the code the person read back), and it frames the outcome — proving phone ownership. It does not name the adjacent sibling send_phone_code or partner_confirm_code, so an agent must infer the ordering from the 'Next: start_checkout' pointer.
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?
Clearly places the call in the flow: the code must already have been read to the person, and the stated next step is start_checkout. It also gives the retry budget ('Five tries per setup'), which is genuine operational guidance. It stops short of naming alternatives such as partner_confirm_code or saying when not to call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a BuzzMeBro setup for the person and returns setup_id and a status_token you must keep for every later call (plus setup_url, a fallback link if you cannot relay a texted code). Only call it after check_building said available and the person has asked you to set it up. No text message is sent and nothing is charged by this call. Next: send_phone_code.
| Name | Required | Description | Default |
|---|---|---|---|
| unit | Yes | Their apartment or unit number as the lobby panel lists it, e.g. "1502", "B" or "PH3". | |
| agent_name | No | Optional: your name as the person knows you (e.g. "ChatGPT", "Claude"), shown on their link page. | |
| postal_code | Yes | The apartment building’s postal code, e.g. "M4B 1B3". Canadian postal codes only for now. | |
| mobile_phone | Yes | The person’s own mobile number. It becomes the first phone the buzzer rings and how they sign in; we text it a code when they open the link. | |
| referral_code | No | Optional BuzzMeBro referral code from a friend. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false. The description adds context the annotations cannot: no text message is sent and nothing is charged, and the status_token must be retained for every later call. That is exactly the side-effect and state-carrying information an agent needs for a non-idempotent creation 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?
Front-loads the core action and the identifiers to retain, then the precondition, then the side-effect reassurance, then the next tool. Every sentence carries distinct operational value with no repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the return contract (setup_id, status_token, setup_url) and does so clearly. Preconditions, side effects, and the follow-up call are all covered, leaving nothing essential unstated for a five-parameter creation tool.
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 (including optional agent_name and referral_code) are already documented in the schema; this is the baseline-3 case. The description adds return-value semantics (setup_url as a fallback for relaying a code) but no parameter-level meaning 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?
States a specific verb and resource (creates a BuzzMeBro setup for the person) and immediately names the artifacts it produces (setup_id, status_token, setup_url). An agent can distinguish it from sibling tools like check_building 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 states the precondition ('Only call it after check_building said available and the person has asked you to set it up') and routes forward to 'Next: send_phone_code.' Both when-to-use and what-comes-next are spelled out, with check_building named as the gating alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads how far the setup has got and says what to do next. Once the person has paid, this call gets their number; when status is "ready" it returns their new BuzzMeBro number and swap_the_buzzer: the steps to get the building to point the buzzer at that number, and ready-to-send messages for building management, the landlord, the concierge, the superintendent or a building portal.
| Name | Required | Description | Default |
|---|---|---|---|
| setup_id | Yes | setup_id from create_setup. | |
| status_token | Yes | status_token from create_setup. Keep it private. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a real side effect that explains the non-read-only annotation: after payment the call 'gets their number', i.e., it provisions a phone number rather than being a pure read. It also describes the conditional 'ready' branch and what that response contains. It doesn't cover failure states or the privacy expectations of the status token beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action before the conditional detail about the ready state. The second sentence is long but every clause conveys distinct return content, so it earns its length despite being dense.
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 explaining returns and does so well for the terminal state (number, swap instructions, pre-written messages). It is incomplete on the non-ready states - the enum of statuses and what a mid-setup response looks like is never spelled out.
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% - both setup_id and status_token are documented in the schema, including the 'Keep it private' note on the token. The description adds nothing about parameter format or provenance, 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?
Clear verb+resource: it reads setup progress and reports next steps. It even names the concrete payload (the new BuzzMeBro number and swap_the_buzzer steps) so an agent knows what the call yields. It stops short of explicitly contrasting itself with siblings like create_setup or check_building, which is why it isn't 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?
The phrase 'Once the person has paid' and 'says what to do next' implies this is the polling/status-follow-up call after create_setup, so usage is inferable. But there is no explicit when-to-call or when-not-to-call statement, no mention of polling cadence, and no named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Starts a partner application with the person’s details and returns application_id and application_token. Only call it when the person has asked to join. No text is sent by this call. Next: partner_send_code.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The person’s name. | |
| Yes | The person’s email. | ||
| persona | Yes | The partner type: how they meet renters (front desk or building staff, leasing agent, mover, tenant insurance, co-living, university, telecom, listing site, relocation, landlord, move-in service, delivery). | |
| building | No | Optional: the building or company they work with. | |
| employer_ok | No | If they work for a building or concierge company: has their employer allowed it? | |
| payouts_off | No | Optional: true for organisations that cannot take money (for example a university or a settlement agency). Their residents still get the perk; no payouts are ever made. | |
| mobile_phone | Yes | The person’s own Canadian mobile number. We text it a code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (destructive=false, openWorld=true, not idempotent), so the bar is lower; the description adds genuinely useful context that no text is sent and that it returns id/token credentials. It doesn't address repeat invocation or what happens on an already-open application, which is the main remaining gap.
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, front-loaded with the action and return values, then the precondition, then the next step. 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?
No output schema, so naming the returned application_id and application_token is necessary and provided. Combined with the precondition and next step, an agent has enough to act, though error/re-entry behaviour on a duplicate application is 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% with enums and lengths documented, so the schema carries parameter meaning. The description adds no parameter-level guidance (e.g., format of mobile_phone or when to set payouts_off), which is the expected baseline-3 outcome.
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 + resource ("Starts a partner application"), states the return payload (application_id, application_token), and names the sibling follow-up (partner_send_code) so the agent can place it in the flow 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?
Gives an explicit precondition ("Only call it when the person has asked to join") and a next-step pointer to partner_send_code. It stops short of naming a true alternative for the other branch, but the when-to-call gate is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
After the person accepted the terms: returns their partner link, code and partner key. The key is shown once; keep it private and use it for the partner_get_* tools. The application token stops working after this call.
| Name | Required | Description | Default |
|---|---|---|---|
| application_id | Yes | application_id from partner_apply. | |
| application_token | Yes | application_token from partner_apply. Keep it private; it collects the partner key once. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantive behavior beyond the annotations: the key is shown only once, must be kept private, and the application token stops working after this call. The token invalidation is a critical side effect the annotations (non-idempotent, non-destructive) do not convey. This is exactly the kind of context the description should supply.
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 precondition and followed by output and side-effect warnings in priority order. No filler; each sentence carries distinct, necessary 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?
Despite no output schema, the description enumerates the return content (partner link, code, key) and covers preconditions, secrecy, and the token-invalidation consequence. An agent has everything needed to invoke it correctly and handle the result.
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 material semantics: it explains that application_token is consumed and stops working after this call, which affects how the parameter should be treated. That is real added meaning over the schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action (collecting/returning the partner link, code, and partner key) and identifies the resource precisely. The reference to partner_get_* tools helps distinguish downstream usage. It is clear but the verb is somewhat passive ('returns') rather than framing the claim operation 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?
Gives a clear precondition ('After the person accepted the terms') and points to the downstream family ('use it for the partner_get_* tools'). However, it does not explicitly exclude or contrast with close siblings like partner_rotate_key or partner_apply, so the agent must infer sequencing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks the texted code. Five tries per application. Next: partner_terms_link.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The digits from the text. | |
| application_id | Yes | application_id from partner_apply. | |
| application_token | Yes | application_token from partner_apply. Keep it private; it collects the partner key once. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnly=false, idempotent=true, destructive=false. The description adds real behavioral context beyond that: a hard five-attempt limit per application, which is exactly the kind of constraint an agent needs to avoid burning retries. It omits what happens on exhaustion (lockout? new application needed?) and what a success returns.
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, front-loaded with the action and immediately followed by the attempt cap and the next step. Efficient, though the telegraphic "Next:" style is slightly cryptic and no sentence explains the outcome of a check.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the burden of explaining results, yet it says nothing about what a successful or failed check returns (e.g., a token or granted flag). It does cover the retry budget and flow position, which is the most critical part for a step in a multi-tool sequence.
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 all three parameters are documented there (code as "the digits from the text", application_id/token sourced from partner_apply). The description's "texted code" merely restates the code field, adding no format or syntax 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?
"Checks the texted code" names a specific verb and resource, and with the title ("the code the person read to you") an agent can identify this as verifying a read-aloud SMS code. It does not, however, distinguish itself from the sibling confirm_phone_code or from partner_send_code, which leaves the boundary to inference.
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?
"Next: partner_terms_link" gives a sequencing cue for what follows, implying this is invoked after a code is texted and before the terms step. There is no statement of when-not to use it, and no pointer to the sibling confirm_phone_code or partner_send_code, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Adds a tracked link with its own code for one location, building or staff member (up to 50). Renters who use it count for this partner, with the same two-months-free perk.
| Name | Required | Description | Default |
|---|---|---|---|
| label | Yes | A name for the link, e.g. "King St location". | |
| partner_key | No | The partner key from partner_claim_key. On REST send it as "Authorization: Bearer <key>" instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safety profile (not read-only, open-world, non-idempotent, non-destructive), so the bar is lowered. The description adds meaningful context beyond them: a hard limit of 50 links, the business semantics that renters count for the partner, and the two-months-free perk. It omits any error or overflow behavior when the cap is exceeded.
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 the scoping limit. The second sentence leans toward marketing language ('same two-months-free perk') but still conveys useful referral semantics. No wasted verbiage overall.
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 write tool with full schema coverage and no output schema, the description supplies the missing conceptual context: what a sublink is, its scope, and its referral effect. It does not explain auth via partner_key or failure behavior, but annotations and schema cover most of the remaining ground.
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 (label, partner_key) are already documented, and the description adds no per-parameter meaning such as how partner_key is obtained or the code format. 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 states a specific verb and resource ('Adds a tracked link with its own code') and scopes it clearly to one location, building or staff member. It is easy to distinguish from read siblings like partner_get_links or partner_list_sublinks. However, it never names an alternative tool, so it falls short of explicit sibling differentiation.
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, no prerequisites, and no mention of alternatives such as partner_claim_key or partner_rotate_key. The '(up to 50)' note hints at a cap but does not explain what to do when it is reached, and nothing indicates when this tool should be chosen over its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Switches off one tracked link: its code stops bringing new apartments. Apartments it already brought stay with the partner.
| Name | Required | Description | Default |
|---|---|---|---|
| sublink_id | Yes | id from partner_list_sublinks. | |
| partner_key | No | The partner key from partner_claim_key. On REST send it as "Authorization: Bearer <key>" instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description usefully disambiguates the blast radius: only future attributions stop, while already-converted apartments remain with the partner. It does not cover reversibility or auth handling beyond what the schema notes.
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 with the action front-loaded and the consequence attached; no filler and nothing that should be trimmed.
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 annotations but no output schema, the description covers what changes and what is preserved. Minor gap: it never says whether the disable can be undone or what a successful call returns.
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 REST Bearer-key note for partner_key), so the description contributes nothing additional about inputs. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('switches off one tracked link') and immediately explains the concrete effect on link codes, which clearly separates it from sibling creation/list tools like partner_create_sublink and partner_list_sublinks.
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 effect wording implies the situation in which you'd call it (retiring an active sublink), but it never states when to use this versus alternatives or prerequisites such as re-enabling being unavailable. Usage must be inferred rather than read.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns ready texts, a resident email, a move-in text and email to forward to new tenants, desk card and move-in insert wording with the partner’s link, links to the partner’s printable move-in package (move-in insert and QR card PDFs with their own QR and code), plus the house rules for sharing (honest words only, no pressure, never ask residents for phone numbers or door codes).
| Name | Required | Description | Default |
|---|---|---|---|
| partner_key | No | The partner key from partner_claim_key. On REST send it as "Authorization: Bearer <key>" instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured fields. The description adds the scope of returned artifacts and an ethical-use constraint (no pressure, never request phone numbers or door codes), which is genuinely useful context. It still says nothing about response shape or how large the kit is.
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 a single front-loaded sentence that begins with the verb and lists concrete artifacts, so nothing is buried. The enumeration is long and slightly run-on, but each listed item carries distinct information rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does the work of describing the return payload by naming every artifact in the kit, which is the key thing an agent needs. Combined with annotations that cover safety and a fully documented single parameter, the definition is nearly complete; only pagination/size or format hints are 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%, and the schema itself explains that partner_key comes from partner_claim_key and how to pass it via the REST Authorization header. The description adds no parameter detail beyond that, 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 uses a specific retrieval verb ('Returns') and enumerates the exact deliverables: ready texts, resident email, move-in text/email, desk card and move-in insert wording, printable package links, and house rules. That content inventory clearly separates it from thin siblings like partner_get_links or partner_get_stats. It stops short of naming any sibling explicitly, so it is clear but not sibling-differentiated.
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 tool versus alternatives such as partner_get_links or partner_program_info, and no prerequisites beyond the implicit partner_key. The 'house rules for sharing' passage is guidance about how to use the returned content, not about tool selection. Usage must be inferred from the content list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the partner’s share link, typed code, a QR code (SVG) and their dashboard address.
| Name | Required | Description | Default |
|---|---|---|---|
| partner_key | No | The partner key from partner_claim_key. On REST send it as "Authorization: Bearer <key>" instead. |
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 usefully discloses the payload shape (four assets, QR as SVG) in the absence of an output schema, but adds nothing about auth requirements, scoping, or behavior for an unclaimed key.
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 listing the returned artifacts with zero filler or redundancy. The most important information (what you get back) is stated 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?
With no output schema, the description rightly enumerates the return payload (share link, typed code, QR SVG, dashboard address), which covers the main gap. It falls short only on the auth/key precondition, which the schema partially handles for REST callers.
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?
One optional-looking parameter at 100% schema coverage, so the schema already carries the semantics. The description adds no meaning to partner_key beyond what the schema states, which is the expected baseline when coverage is complete.
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 (returns) plus four concrete resources: share link, typed code, QR code in SVG, and dashboard address. This clearly separates it from sibling writers like partner_create_sublink or partner_rotate_key, though it never names the alternative tools 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 description states only what comes back, with no when-to-use framing, no prerequisites (e.g., that a claimed key must exist first), and no indication of when one would call this versus partner_get_kit or partner_program_info.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns status, visits, signups, free months, paying apartments, collected revenue, earnings by state (on hold, ready, paid, reversed), the share ledger (apartments as codes only, never names or addresses) and payout history. Quote only these numbers.
| Name | Required | Description | Default |
|---|---|---|---|
| partner_key | No | The partner key from partner_claim_key. On REST send it as "Authorization: Bearer <key>" instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely new behavioral context: the share ledger is pseudonymised to codes and never exposes names or addresses, and the "quote only these numbers" instruction constrains the agent from fabricating or extrapolating figures.
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, with the returned-fields inventory front-loaded before the quoting constraint. The long comma-list is information-dense rather than padded, though it is closer to a bullet dump than to flowing prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing return contents and does so thoroughly, including the earnings-state breakdown and the privacy scoping of the share ledger. It stops short of stating time-range or scoping behaviour and what an empty/unlinked partner returns.
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 partner_key parameter is well documented there, including the alternative REST bearer-header usage. The description adds no further parameter meaning, 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?
The description names the resource (a partner's stats) and enumerates its exact contents: status, visits, signups, free months, paying apartments, collected revenue, earnings by state, share ledger and payout history. That enumeration distinguishes it cleanly from siblings such as partner_get_links, partner_payout_link and partner_program_info.
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 and no alternative tool is named — an agent is not told whether to call this before or instead of partner_get_kit, partner_program_info or partner_payout_link. "Quote only these numbers" is a downstream constraint on the returned data, not selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the extra tracked links (one per location, building or staff member) with each one’s visits, apartments and earnings. Every apartment and every dollar rolls up to the partner.
| Name | Required | Description | Default |
|---|---|---|---|
| partner_key | No | The partner key from partner_claim_key. On REST send it as "Authorization: Bearer <key>" instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds the worthwhile detail that results are per-location/building/staff entries and that values roll up to the partner, but says nothing about volume, pagination 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 with no filler; the resource definition and the roll-up behavior are front-loaded and each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only listing tool there is no output schema, and the description compensates by naming the returned fields (visits, apartments, earnings) and the roll-up semantics. Minor gaps remain around result size and pagination, but nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single partner_key parameter already documents its origin (partner_claim_key) and the REST Authorization header convention. The description adds no parameter-level meaning, 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?
The description gives a specific verb ('Lists') and resource ('the extra tracked links'), and even enumerates what each entry contains. It does not, however, name or contrast itself with the close sibling partner_get_links, so an agent must infer which of the two link-listing tools to pick.
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 explicit when-to-use guidance and no exclusion, despite sibling tools partner_get_links, partner_create_sublink and partner_disable_sublink covering closely adjacent territory. The scope word 'extra' hints at the distinction but leaves the agent to infer it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a one-time link to a BuzzMeBro page that sends the person to Stripe’s own secure page, where THEY confirm their identity and add their bank. You never see or type bank details. Payouts start once they have at least $25 ready. First-time setup only: once payouts work, payout changes are made by the partner on their signed-in dashboard. The partner gets a text whenever this link is made.
| Name | Required | Description | Default |
|---|---|---|---|
| partner_key | No | The partner key from partner_claim_key. On REST send it as "Authorization: Bearer <key>" instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly=false, idempotent=false, openWorld=true), the description discloses substantial behavior: a one-time link, privacy ("You never see or type bank details"), a $25 payout threshold, the first-time-only constraint, and a side effect ("The partner gets a text whenever this link is made"). These are exactly the traits an agent needs and none are in the structured fields.
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 return value is front-loaded in the first sentence, followed by tightly scoped sentences covering privacy, the payout threshold, the first-time-only limit, and the SMS side effect. Every sentence earns its place 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 single-parameter tool with no output schema, the description fully covers what is returned (the one-time link), what the flow entails, and the constraints. 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% and the single partner_key parameter is fully documented in the schema itself, including the REST Authorization header variant. The description adds no parameter-level detail, 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 states a specific verb and resource: it 'Returns a one-time link' that routes the partner to Stripe to confirm identity and add a bank. It is clearly distinguishable from siblings like partner_create_sublink, partner_get_links, and partner_claim_key because it names the Stripe bank-onboarding flow and the first-time-only scope.
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 a clear usage condition: 'First-time setup only: once payouts work, payout changes are made by the partner on their signed-in dashboard.' This tells the agent when the tool is appropriate and points to the alternative path (the partner dashboard), though it does not name a sibling tool explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns how the partner program works: the 50% share of collected revenue, what counts and what does not, when and how payouts happen, the rules, and the steps to join. Call it first and explain it to the person before applying. Stores nothing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive, closed-world, so the safety profile is covered. The description still adds a genuine behavioral fact beyond them — 'Stores nothing' — and enumerates the categories of content returned. It doesn't describe the return format (prose vs. structured), which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the verb and the enumerated payload in one sentence, followed by a short action directive and a terse persistence note. The inline list is dense but each item earns its place; only the trailing 'Stores nothing' fragment is slightly abrupt.
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-parameter, read-only, no-output-schema tool, the description carries the burden of telling the agent what comes back, and it does so by naming the content categories. It is essentially complete; only the response format and any length expectations are 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?
The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. Schema coverage is 100% and no enum or nested semantics exist to explain.
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 how the partner program works) and enumerates the actual content: revenue share, eligibility, payout timing, rules, and join steps. Combined with the routing instruction toward applying, an agent can distinguish it from partner_apply, partner_get_kit, or partner_get_stats 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 says to 'call it first and explain it to the person before applying,' which gives both ordering and the condition that selects this tool over the apply flow. It does not name the sibling tool directly or say when this tool is unnecessary, so it falls just short of full when/when-not coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revokes the current partner key and returns a new one (shown once). Use it if the key may have leaked. The partner gets a text whenever the key is replaced.
| Name | Required | Description | Default |
|---|---|---|---|
| partner_key | No | The partner key from partner_claim_key. On REST send it as "Authorization: Bearer <key>" instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this non-read-only, non-idempotent and destructive, and the description adds substantive context beyond them: the old key is revoked, the new key is displayed only once, and the partner is notified by text. These are exactly the side effects and irreversibility details an agent needs before invoking a rotation.
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 no filler; the core action is front-loaded and each sentence contributes a distinct fact (what happens, when to use, side effect).
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 mutation with no output schema, the description covers outcome and side effects well, and annotations cover the safety profile. It is slightly incomplete in that it doesn't state the authorization requirement for obtaining/using the current key, though the schema covers that surface.
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 partner_key parameter is fully documented there including the REST Bearer alternative. The description adds no parameter meaning 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?
The description states a specific verb and resource ('Revokes the current partner key') plus the effect ('returns a new one'). It is clearly distinguishable in substance from partner_claim_key, but it never names a sibling or explicitly contrasts itself, so it falls short of a 5 by this rubric.
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 it if the key may have leaked' gives a concrete trigger condition for selecting this tool. No when-not guidance or named alternatives (e.g., partner_claim_key for first-time claim) are provided, which keeps it below 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Texts a 6-digit code to the mobile number in the application (never any other number). Ask the person to read it to you, then call partner_confirm_code. Each application gets 3 codes, at least a minute apart.
| Name | Required | Description | Default |
|---|---|---|---|
| application_id | Yes | application_id from partner_apply. | |
| application_token | Yes | application_token from partner_apply. Keep it private; it collects the partner key once. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing a concrete rate limit ('3 codes, at least a minute apart') and a delivery-scope constraint (only the application's number). This is exactly the kind of side-effect context the annotations (openWorldHint=true, idempotentHint=false) cannot express on their own.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the primary action, then the follow-up step, then the constraint. No filler or restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a 2-param tool with full schema coverage and no output schema: purpose, next step, and rate limit are all covered. It stops short of explaining behavior at the 3-code limit or failure modes, a minor omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the schema and the description adds no parameter-level syntax or format 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?
States a specific verb ('Texts') and specific resource ('6-digit code') with an explicit destination constraint ('the mobile number in the application, never any other number'). An agent can distinguish this from sibling send_phone_code/confirm_phone_code flows via the named follow-up step partner_confirm_code.
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 sequencing guidance ('Ask the person to read it to you, then call partner_confirm_code'), which routes the agent to the correct next tool. It does not, however, state when NOT to use this versus the sibling send_phone_code, so the when-not case 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.
Returns a one-time link to the partner terms. Give it to the person: they read the terms and press Accept themselves. You cannot accept for them. When they say it is done, call partner_claim_key.
| Name | Required | Description | Default |
|---|---|---|---|
| application_id | Yes | application_id from partner_apply. | |
| application_token | Yes | application_token from partner_apply. Keep it private; it collects the partner key once. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and idempotentHint=false, and the description supplies the reason: the link is one-time and the acceptance must be performed by the human, not the agent. It also discloses the required follow-up sequencing, adding real behavioral context beyond the safety hints.
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, front-loaded with the return value, then the usage constraint, then the next action. No sentence is redundant and nothing is buried.
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 tool with full schema coverage, no nested objects, and no output schema, the description covers the return value, the human-in-the-loop requirement, and the workflow continuation. Nothing needed 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 itself explains each parameter's origin ('from partner_apply') and privacy constraint. The description adds no parameter-level detail, so the baseline 3 applies when the schema does all the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Returns) and resource (one-time link to the partner terms) in the opening sentence. It also differentiates from the sibling partner_claim_key by naming it as the follow-up step, so an agent can distinguish the two without opening either 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 instructs what to do with the link ('Give it to the person'), what the agent cannot do ('You cannot accept for them'), and the exact condition for the next call ('When they say it is done, call partner_claim_key'). This is a full when/when-not/alternative specification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Texts a 6-digit code to the mobile number given in create_setup (never to any other number). Tell the person a text is coming and ask them to read the code to you, then call confirm_phone_code. Call again only if it has not arrived after a minute; each setup gets 3 codes.
| Name | Required | Description | Default |
|---|---|---|---|
| setup_id | Yes | setup_id from create_setup. | |
| status_token | Yes | status_token from create_setup. Keep it private. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true), so the description only needed to add non-obvious behavior. It does: a per-setup rate limit of 3 codes, a retry delay, and an irreversible recipient restriction ('never to any other number'). It does not say what the call returns or how a failure surfaces, which is the remaining gap.
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, front-loaded with the action and its recipient constraint before the follow-up instructions. Every clause carries operational information; nothing restates the tool name or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter action with no output schema, the description supplies the practical loop (send → read code → confirm), the retry rule, and the invocation cap. Only the response behavior after sending is left unstated, a minor omission given the lightweight 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% and both parameters (setup_id, status_token) are already documented with their origins and the privacy caveat. The description reinforces setup origin ('each setup gets 3 codes') but adds no syntax or failure-mode meaning 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 ('Texts a 6-digit code to the mobile number') and immediately scopes it: the number comes from create_setup and 'never to any other number'. The single-destination constraint separates it from the generic sibling partner_send_code without the agent needing either 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 sequencing ('then call confirm_phone_code') and an explicit retry condition with an exclusion ('Call again only if it has not arrived after a minute'), plus the hard cap of 3 codes per setup. Both when-to-use and when-not-to-retry are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
After confirm_phone_code: creates the person’s BuzzMeBro account and apartment and returns payment_url, Stripe’s own secure page where the person approves a card, Apple Pay, Google Pay or Link (with the free month when it applies, nothing is charged until it ends). Give them the link or message_for_the_person; you never see or type card details. Calling it again returns a fresh link for the same apartment.
| Name | Required | Description | Default |
|---|---|---|---|
| setup_id | Yes | setup_id from create_setup. | |
| status_token | Yes | status_token from create_setup. Keep it private. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond annotations: it creates the account and apartment (mutation), returns a Stripe payment URL, is free until the month ends, and never exposes card details to the agent. It also explains the idempotent-equivalent behavior despite annotations already hinting at it.
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 precondition and outcome, then layers detail. Slightly dense with parenthetical asides, but no sentence 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?
For a 2-parameter mutation tool with no output schema, the description covers preconditions, return value, security posture, idempotency, and next steps, leaving nothing material for the agent to infer.
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 workflow context that setup_id and status_token come from create_setup and that the token must stay private, which reinforces the schema's privacy note.
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 outcome: creates the account and apartment and returns payment_url. It distinguishes itself from siblings by naming the precondition (after confirm_phone_code) and the output artifact, so an agent can identify 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?
Explicitly sequences the call after confirm_phone_code and explains what to do with the result (give the link to the person or use message_for_the_person). It also covers the re-call case: calling it again returns a fresh link for the same apartment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
partner_apply3 fields changedInput schema / properties / payouts_offAdded value: +{
+ "description": "Optional: true for organisations that cannot take money (for example a university or a settlement agency). Their residents still get the perk; no payouts are ever made.",
+ "type": "boolean"
+}Input schema / properties / persona / descriptionPrevious value: -"How they meet renters."New value: +"The partner type: how they meet renters (front desk or building staff, leasing agent, mover, tenant insurance, co-living, university, telecom, listing site, relocation, landlord, move-in service, delivery)."Input schema / properties / persona / enumPrevious value: -[
- "front_desk",
- "property_manager",
- "condo_board",
- "leasing_agent",
- "mover",
- "student_housing",
- "creator",
- "other"
-]New value: +[
+ "front_desk",
+ "property_manager",
+ "condo_board",
+ "leasing_agent",
+ "mover",
+ "student_housing",
+ "tenant_insurance",
+ "co_living",
+ "telecom",
+ "listing_site",
+ "relocation",
+ "landlord",
+ "move_in_service",
+ "delivery",
+ "creator",
+ "other"
+]partner_create_sublinkpartner_disable_sublinkpartner_list_sublinkscheck_buildingconfirm_phone_codecreate_setupget_setup_statuspartner_applypartner_claim_keypartner_confirm_codepartner_get_kitpartner_get_linkspartner_get_statspartner_payout_linkpartner_program_infopartner_rotate_keypartner_send_codepartner_terms_linksend_phone_codestart_checkoutBuzz in deliveries and guests: apartment access codes, timed or recurring entry, and access history.
Split rent and utilities by room, settle up and generate roommate agreements. Free.
Rent, rooms and tenants for rent-by-the-room landlords: who is late, vacancies, reminders.
AI food ordering across Canada — 17,000+ restaurants, 89 cities, real UberEats + DoorDash.
Add one secure layer between your agents and this server.
