SF move agent: rentals with sources, no-SSN banking routes, and your move plan and drafts.
Scored across 11 tools
The move_task family is large but each verb suffix (answer/defer/draft) names a distinct action, and the other tools cover clearly separate resources. The only real ambiguity is move_task vs move_tasks, though the descriptions explicitly distinguish a single read-only task from a prioritized next-action feed.
All names are lowercase snake_case and the move_task_* prefix is consistent, but conventions mix imperative verbs (search_listings, start_move) with noun-style names (move_plan, listing_requirements, newcomer_options). Readable and predictable overall, with minor deviation.
11 tools is well within the ideal range for the server's scope. Each tool covers a distinct part of the newcomer/move workflow—searching, comparing requirements, offering newcomer options, starting a move, and managing tasks—without redundant helpers.
The lifecycle around listing search, requirement comparison, and task progression is well covered, with read, answer, defer, draft, and history operations. Minor gaps exist: walk and research tasks have no execution path here, and sending or submitting is deliberately left to the PutRoots web app.
For one listing URL from search_listings: what the landlord requires, what the renter filled in, and the gap on each line — income, credit, SSN, deposit, pets, co-signer, documents. Each line carries the landlord's own sentence it was read from, plus where the rule came from and when we fetched it. Requires the renter's own PutRoots account (the comparison is against qualifications they filled in). It returns no overall verdict, by design.
| Name | Required | Description | Default |
|---|---|---|---|
| listing_url | Yes | The listing's url, exactly as returned by search_listings. |
| Name | Required | Description |
|---|---|---|
| items | Yes | |
| price | Yes | |
| source | Yes | |
| listing | Yes | |
| summary | No | |
| triage_tier | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and non-destructive annotations, the description adds meaningful behavioral context: the comparison depends on the renter's own stored qualifications, each line includes provenance and fetch time, and the tool intentionally returns no overall verdict. This gives an agent a clear model of what the tool does and does not decide.
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 information-dense sentences: scope, output detail, provenance, account requirement, and a design caveat. There is no repetition or filler, and the most important usage boundary appears early.
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 a single required parameter and an output schema already present, the description supplies all essential context: listing source, required user scope, compared dimensions, provenance of each line, and the explicit lack of a verdict. Nothing critical is missing for correct selection and 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?
The only parameter, listing_url, is fully documented in the schema with 'exactly as returned by search_listings,' and the description reinforces that source. With 100% schema coverage, the baseline of 3 is appropriate; the description doesn't add new parameter syntax or format details.
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 resource scope ('one listing URL from search_listings') and the exact output: landlord requirements, renter-filled qualifications, and the gap per line, with examples of dimensions. It is unambiguous and easily distinguished from sibling tools like search_listings or move_plan by focusing on requirement comparison rather than listing search or move management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use it for a single listing obtained from search_listings, and it requires the renter's own PutRoots account. It doesn't explicitly name alternative tools or state when not to use it, but the input source and account prerequisite provide strong situational guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The signed-in person's move events after an epoch-millisecond timestamp, oldest first — drafted, sent, called, answered, done, skipped. Use it to answer "what changed since we last spoke" without re-reading the whole plan. Capped; more says how many were left out.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Most recent N of the matches (default 100, max 500). | |
| since | No | Epoch milliseconds; 0 for everything. |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| more | Yes | |
| since | Yes | |
| events | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and destructiveHint annotations, the description discloses meaningful behavior: the scope is the signed-in person's events, results are sorted oldest first, the event types are enumerated, and results are capped with an indication of how many were omitted. This adds real value not present in the annotations or 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?
The description is three short sentences, each earning its place: scope and ordering, use case, and cap behavior. The most important identifying information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (100% parameter coverage), annotations, and output schema, the description covers everything an agent needs to invoke this correctly: event scope, ordering, event types, use case, and limit behavior. There are no critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds semantic meaning for `since` by framing it as a 'since we last spoke' checkpoint and for `limit` by explaining the cap behavior and the 'more' count. This goes slightly beyond the schema's purely mechanical descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource ('move events') and a precise verb/operation: retrieving events after a timestamp, oldest first. It also enumerates the event kinds and frames the tool's purpose as answering 'what changed since we last spoke,' which clearly distinguishes it from siblings like move_plan or move_tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear, explicit use case: answer incremental 'what changed' questions without re-reading the whole plan. It does not explicitly name sibling alternatives or state when not to use it, but the provided context is enough for an agent to route appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The whole move at a glance for the signed-in person: days to move day, how many tasks there are, how many are settled, how many can be done right now, how many are blocked and how many are overdue, plus the critical path. Two rulers share that answer and they are not interchangeable: total and done count every task in the move, while actionable, blocked and overdue count only tasks that have been unlocked so far. Blocked therefore mixes two things — tasks missing an answer from the person, and tasks whose prerequisites aren't finished so they haven't been generated yet. Report the numbers as given; don't subtract one from another.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| d0 | Yes | |
| ok | Yes | |
| done | Yes | Settled: done, sent, called, replied or marked not applicable (full ruler). |
| total | Yes | Every task in this move (full ruler). |
| health | Yes | |
| blocked | Yes | total - done - actionable: tasks missing an answer AND tasks not yet unlocked, together. |
| overdue | Yes | Past due, not in flight, not blocked (unlocked ruler). |
| actionable | Yes | Unlocked and not waiting on an answer (unlocked ruler). |
| days_to_d0 | Yes | |
| critical_path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, so the safety profile is known. The description adds behavioral nuance: explains that blocked mixes two types, and instructs to report numbers as given without subtraction. This adds value beyond 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?
Dense but efficient; every sentence adds meaning, including the crucial 'don't subtract' instruction. Front-loaded with the purpose.
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 no-param read-only summary. Output schema exists, so return values are covered. Description explains the semantics of each number, which is essential for correct interpretation.
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?
No parameters exist, so the schema covers everything. Baseline 4 applies; description doesn't need to add parameter info.
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: 'the whole move at a glance' for the signed-in person, enumerating the five numbers and critical path. Clearly distinct from sibling tools like move_tasks (which likely lists tasks) and move_events (events).
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?
Does not explicitly state when to use this vs alternatives, though it implies a quick overview. It does not name sibling tools or exclusion conditions. The description focuses on interpretation rather than routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One task on the signed-in person's move: what it is, when it is due, what state it is in, any draft already prepared, and which fields it is waiting on them to answer. Read-only — opening a task leaves no trace. It does not tell you whether the task is in flight: that needs evidence lookups this cheap read skips on purpose. move_tasks is the only place "in progress" appears.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | A task id exactly as move_tasks / move_plan returned it. |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| ok | Yes | |
| due | Yes | |
| kind | Yes | |
| actor | Yes | |
| draft | No | Prepared, never sent. |
| state | Yes | |
| title | Yes | |
| dlabel | Yes | |
| due_day | Yes | |
| missing | No | |
| missing_text | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint and destructiveHint, but the description adds meaningful behavioral detail beyond them: 'opening a task leaves no trace,' it is a 'cheap read,' and it intentionally skips evidence lookups. This gives the agent useful expectations about side effects and limitations. No contradiction with 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?
Three sentences, each earning its place: the first enumerates the returned content, the second states read-only/no-trace behavior, and the third gives the key limitation and routes to the sibling tool. It is front-loaded with purpose and has 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 read-only tool with an output schema and strong annotations, the description is complete: it covers scope, safety, behavioral limitations, and the relevant sibling alternative. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single task_id parameter already includes provenance guidance ('exactly as move_tasks / move_plan returned it'). The description adds context about scope but does not need to add parameter-level semantics; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it returns one task on the signed-in person's move and enumerates exactly what it contains (due date, state, draft, waiting fields). It also distinguishes itself from move_tasks by noting that move_tasks is the only place 'in progress' appears.
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 explicitly says what this tool does not tell you (whether the task is in flight) and names move_tasks as the alternative where that information appears. It also scopes the tool to the signed-in person's move, giving clear context for when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fills in one field the signed-in person's task is waiting on (the names come back in missing from move_task or move_task_draft). Only fields that task is actually asking for are accepted, and only values we can store — anything else is refused rather than silently dropped. Pass what the person actually said; never a guess or a plausible default.
| Name | Required | Description | Default |
|---|---|---|---|
| field | Yes | A field name from the task's missing list. | |
| value | Yes | What the person said. Not inferred, not a placeholder. | |
| task_id | Yes | A task id exactly as move_tasks / move_plan returned it. |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| ok | Yes | |
| field | Yes | |
| state | No | |
| closeout | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations' read-only/destructive flags, the description discloses important behavior: unaccepted fields or unrepresentable values are refused rather than silently dropped, and guesses or plausible defaults are forbidden. This gives the agent a clear model of the tool's rejection behavior, though it does not describe persistence, reversibility, or 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?
The description is three sentences with no filler. It front-loads the core purpose, then packs the key constraints—source of field names, strict acceptance policy, and the no-guessing rule—into the remaining sentences. Every 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 tool with only three required parameters and an output schema present, the description covers the essential selection and invocation knowledge: the field source, the acceptance constraints, and the expected value semantics. It does not explain return values, but that is less critical given the output schema and the small parameter 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 coverage is 100%, so the schema already documents all three parameters. The description adds meaningful semantics by explaining where field names originate (the missing list), what value should contain ('what the person actually said,' never inferred), and reinforcing that task_id must come from move_tasks/move_plan without modification.
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: 'Fills in one field the signed-in person's task is waiting on.' It also clarifies that field names come from the missing list returned by move_task or move_task_draft, which distinguishes it from sibling task tools like move_task, move_task_defer, and move_task_draft.
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 context for when to use the tool: after move_task or move_task_draft returns a missing list, and only when answering one of those requested fields. It stops short of explicitly naming a sibling alternative to use instead, but the 'Only fields that task is actually asking for are accepted' restriction effectively tells the agent when not to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
later = push it out; it comes back on its own in three days. not_applicable = it doesn't apply to this person; it leaves the list, stops counting against the move, and anything waiting on it can go ahead. undo = put a ruled-out task back. Only on the person's say-so: ruling a task out changes what the rest of the move waits on.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ||
| task_id | Yes | A task id exactly as move_tasks / move_plan returned it. |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| state | Yes | |
| later_until | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important side effects: deferred tasks return in three days, ruled-out tasks leave the list and stop blocking dependent work, and undo reverses that. This adds real behavioral context beyond the annotations, which only state that the operation is not read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: each mode is paired with its consequence in a clear, scannable format. The permission caveat is added without clutter, though a slight restructuring could improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation tool with an output schema, the description covers all modes, their outcomes, and a key authorization nuance. It is largely self-sufficient, though it stops short of explaining how to choose among sibling task tools.
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 schema documents task_id, and the description adds meaning to all three mode enum values. With schema coverage at 50%, the description compensates for the undocumented enum by explaining exactly what each mode does.
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 clarifies the tool's purpose through its three modes, explaining what happens for 'later', 'not_applicable', and 'undo'. It clearly identifies the resource (a task) and the action (defer, rule out, or restore), though it relies partly on the title to summarize the whole operation.
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 mode definitions imply when each option should be used and even warn that ruling a task out requires the person's say-so. However, it does not explicitly contrast this tool with siblings like move_task or move_task_answer, nor does it state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prepares one task for the signed-in person and stops. It writes the email or the call script and hands it back; it never sends, dials, submits or pays, and no MCP tool can. The person presses send themselves in PutRoots. It covers email and call tasks, plus a form-filling task that has already been tried and given up on (that falls back to a letter or a call). It cannot start the other two kinds: walk tasks (filling a form on a provider's own site) and research tasks (finding candidates, booking a viewing, filling a rental application) have no execution path here yet and will come back saying the task is neither an email nor a call. Those are done in the PutRoots web app; say so rather than retrying. If it comes back blocked, the task is waiting on a field only the person can answer — use move_task_answer, then call this again.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Recipient, when the person supplies one: an email address for an email task, a phone number for a call task. Leave it out to use the recipient we already have. | |
| task_id | Yes | A task id exactly as move_tasks / move_plan returned it. |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| draft | No | to / subject / body, or the call script. Prepared, not sent. |
| state | Yes | drafted = ready for them to press send; blocked = waiting on an answer. |
| missing | No | |
| missing_text | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnlyHint=false and destructiveHint=false, and the description adds meaningful behavioral context beyond those: it writes drafts only, never sends or pays, and no MCP tool can send. It also explains the 'blocked' outcome and what causes it, which is valuable runtime behavior not visible in the schema or annotations. No contradiction exists between the description and 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 long but densely informative, front-loaded with the core behavior and then covering limitations, fallbacks, and error handling. A few phrases are somewhat redundant with the title and annotations, such as repeating 'never sends' and adding 'no MCP tool can,' which prevents a perfect score.
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 complexity, the description is remarkably complete: it explains supported task types, unsupported task types and how to handle them, the fallback path for form-filling tasks, the blocked outcome and its remedy. Since an output schema exists, the lack of return-format detail is not a 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%, so the schema already fully documents both parameters. The description does not add extra parameter-level meaning beyond the schema, which is acceptable given the baseline of 3 for complete schema coverage. The main behavioral context (draft-only, email/call distinction) is relevant but not tied to individual parameter semantics.
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-resource pair: it 'prepares one task' by writing an email or call script and handing it back. It clearly distinguishes itself from siblings by emphasizing it never sends, dials, submits, or pays, and explicitly says which task types it can and cannot handle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use and when-not-to-use guidance: it covers email, call, and fallback form-filling tasks, but cannot start walk or research tasks, which 'are done in the PutRoots web app; say so rather than retrying.' It also provides a recovery alternative for blocked tasks: 'use move_task_answer, then call this again.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What the signed-in person should do next on their move: one task to press, a few short lines after it, and a count of everything folded away. This is deliberately one screen, not the task list — picking which one matters is our job, not the caller's, and a task whose prerequisites aren't done doesn't appear at all (its prerequisite does). Use move_plan for totals. This is also the only place a task is marked in flight (we have evidence they already started it); move_task does not carry that flag.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| hero | Yes | The single next thing, or null with blockedReason set. |
| rows | Yes | |
| moreCount | Yes | |
| blockedReason | No | no_move / nothing_open / all_in_flight — why there is no next thing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite readOnlyHint=true and destructiveHint=false already covering safety, the description adds valuable behavioral detail: prerequisite filtering, single-screen intentional scope, server-side selection ('our job, not the caller's'), and the unique in-flight marker. No contradiction with 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?
Three dense sentences, each adding unique value: output summary, design rationale/filtering, and sibling differentiation. Front-loaded and free of 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 zero-parameter read-only tool with an output schema, the description covers purpose, scoping, exclusions, and a distinctive behavioral flag. Nothing essential 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?
Tool has 0 parameters, so baseline 4 applies. The description focuses on output semantics, which is appropriate; no parameter explanation is needed.
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 specifies the resource: what the signed-in person should do next (one task, a few lines, and a count). It explicitly contrasts with 'the task list' and points to move_plan, so siblings are distinguishable. The title reinforces the purpose.
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 explicit when-to-use guidance: use for the next recommended action, avoid for task lists, use move_plan for totals, and note that move_task does not carry the in-flight flag. This leaves little ambiguity about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The doors a newcomer has to walk through besides the apartment: opening a bank account, a credit card, a phone plan, or getting an SSN — specifically the routes that work without an SSN or US credit history. Returns real branches and stores (address, hours, phone) plus the no-branch options, each with its source and the date it was checked, and our firsthand account where we did it ourselves.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | bank = checking account, card = credit card, sim = phone plan, ssn = the SSN itself. |
| Name | Required | Description |
|---|---|---|
| topic | Yes | |
| places | Yes | |
| options | Yes | |
| prefNote | No | |
| prefScope | No | |
| places_total | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only and non-destructive behavior. The description adds value beyond that by disclosing the return characteristics: real branches/stores with address, hours, and phone, no-branch options, source information, the date checked, and firsthand accounts. This gives an agent useful context about provenance and trustworthiness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loads the newcomer/no-SSN context before enumerating the return contents. The opening metaphor is slightly ornamental, but the rest of the sentence earns its place by specifying scope and output details.
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, read-only tool with an output schema and complete schema documentation, this description covers audience, scope, the qualifying condition (no SSN/credit history), and the return format including provenance and date. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the sole parameter, topic, has an enum and clear descriptions for each value. The tool description reinforces the domain but does not materially extend the schema's parameter semantics, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete resource—bank accounts, credit cards, phone plans, and SSN routes—and the specific scope: routes that work without an SSN or US credit history. It also clearly says what the tool returns, making it easy to distinguish from the sibling listing/search and move tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'specifically the routes that work without an SSN or US credit history' clearly signals when this tool is appropriate, reinforced by the title 'for someone with no SSN yet.' It does not describe when-not-to-use scenarios or name an explicit alternative, but no sibling tool appears to compete for the same use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search PutRoots' San Francisco rental index. Every row carries its source, the date we last saw it, and whether the landlord stated any requirements at all. Use this when someone asks what's available in SF at a price / bedroom count / neighborhood. Without a signed-in PutRoots account this searches the free sample only (3 listings per bedroom tier) and says so, with the true total.
| Name | Required | Description | Default |
|---|---|---|---|
| beds | No | Bedroom tier. "room" means a room in a shared place. | |
| hood | No | Neighborhood name, matched loosely (e.g. "Mission", "Sunset"). | |
| limit | No | How many to return (default 10, max 25). Newest first. | |
| max_price | No | Max monthly rent in USD. Listings with no stated price are excluded when you set this — we don't let unpriced posts through a price filter. | |
| min_price | No | Min monthly rent in USD. |
| Name | Required | Description |
|---|---|---|
| gated | Yes | true = free sample only (anonymous or partner key); total still tells the true index size. |
| total | Yes | |
| matched | Yes | |
| listings | Yes | |
| searched | Yes | |
| not_checked_vs_budget | No | |
| listings_with_no_stated_requirements | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/destructive annotations, the description discloses meaningful behavioral details: every row carries provenance fields, and unauthenticated usage returns a limited free sample but still reports the true total. This is exactly the kind of context that helps an agent set expectations and avoid surprising the user.
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 three sentences with no wasted words. It front-loads the core action, then adds provenance, usage context, and authentication behavior in a logical, compact order. Every 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?
Despite its brevity, the description covers what the tool does, when to use it, what returned rows contain, and a critical access limitation. With a full input schema, annotations, and an output schema present, nothing essential is missing for an agent to select and invoke this tool 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 each parameter thoroughly. The description adds domain-level context about price/bedroom/neighborhood but does not need to add per-parameter detail. A baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Search PutRoots' San Francisco rental index.' It also clarifies the distinctive provenance aspects (source, last-seen date, whether requirements were stated), which separates it from generic search tools. The purpose is immediately understandable and sufficiently specific.
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 explicitly says to use this tool 'when someone asks what's available in SF at a price / bedroom count / neighborhood,' which provides a clear trigger condition. It does not enumerate exclusions or explicitly name alternatives, but sibling tools are not close enough to require detailed differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
When someone has just signed a lease, accepted an offer, or otherwise has a move coming: returns a PutRoots link that pre-fills their move date and new address and attributes them to you. Nothing is created on their behalf — they sign up themselves by opening the link. Use the returned id with GET /v1/handoffs/{id} to see which stage of the move they are in.
| Name | Required | Description | Default |
|---|---|---|---|
| d0 | No | Move-in day, YYYY-MM-DD. | |
| to | No | The new address, as one line. | |
| stage | No | Which stage of the journey they are in right now, if you know it. | |
| trigger | Yes | What set the move off: lease_signed, offer_accepted, relocation_approved, or your own short label. | |
| profile_seed | No | Reserved. Accepted but not applied yet — the person fills their own profile after signing up. |
| Name | Required | Description |
|---|---|---|
| d0 | No | |
| id | Yes | |
| to | No | |
| url | Yes | |
| stage | No | |
| dry_run | Yes | true when called with a pr_test_ key. |
| partner | Yes | |
| trigger | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It discloses the key non-obvious behavior that the mover signs up themselves by opening the link and that nothing is created on their behalf, plus attribution back to the caller. The 'nothing created' phrasing is scoped to the mover side and does not directly contradict readOnlyHint=false, though the server-side handoff creation remains somewhat implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it states the use case and result first, then gives the follow-up endpoint. Each sentence carries useful information, with only minor redundancy between the title's 'nothing created' and the description's fuller explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with five parameters, one required trigger, an output schema, and annotations, the description provides the core 'when, what, and next step' an agent needs. It is slightly terse around optional fields and the exact side effects of creating the handoff, but the schema and output schema fill most remaining gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema documentation covers all five parameters with 100% coverage, so the description does not need to repeat parameter definitions. The description adds only the high-level mapping of move date and new address to pre-filled link fields, which is helpful but not essential beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: it returns a PutRoots signup link for someone with an upcoming move, and clarifies that no mover-side account is created by this call. The title reinforces the purpose, but it does not explicitly differentiate this tool from sibling tools like move_plan or move_events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use triggers ('just signed a lease, accepted an offer, or otherwise has a move coming') and even provides a follow-up action using the returned id. It does not name sibling alternatives or state when not to use the tool, so it lacks full routing guidance.
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.
listing_requirementsmove_eventsmove_planmove_taskmove_task_answermove_task_defermove_task_draftmove_tasksnewcomer_optionssearch_listingsstart_moveFree agent home for live work, trust, repeat return and high-throughput fleet routing.
Unified book, desk, calendar, prices, and rates for agents. Sign up, pay, pull.
Current US rental market data for AI agents: 1,500+ submarkets, monthly rent + vacancy + trends.
Permit-verified ADU rentals, pre-approved plans and cited ADU rules for LA, San Diego, SF and NYC.
Add one secure layer between your agents and this server.
