rank_room_matchesFind rooms and score them against student preferences such as budget, campus distance, room type, and trust signals.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| features | No | ||
| campus_id | No | ||
| max_budget | No | ||
| available_from | No | YYYY-MM-DD. | |
| max_distance_km | No | ||
| preferred_room_type | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds that the tool scores rooms, but it does not disclose behavioral traits like result ordering, pagination, or how trust signals are computed. With annotations present, the description doesn't need to restate safety, but it also doesn't enrich behavioral context meaningfully.
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 a single, front-loaded sentence with no filler. It immediately states the action and key criteria, making it highly concise and well-structured for the information it conveys.
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 8 parameters, low schema coverage, no output schema, and only high-level annotations, this one-sentence description is insufficient. It does not explain ranking logic, return format, or how parameters like features or trust signals are used, leaving the tool under-specified for a task of this complexity.
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 very low (13%), so the description carries the burden of explaining parameters. It mentions budget, campus distance, and room type, which map to max_budget, max_distance_km, and preferred_room_type. However, it omits many parameters (features, campus_id, query, limit) and does not explain the 'trust signals' factor, leaving significant gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds rooms and scores them against preferences, which is specific and distinguishes it from a plain search. It names the scoring criteria (budget, distance, room type, trust signals) but does not explicitly reference sibling tools, so it stops short of full 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?
The description implies this tool is for preference-based ranking but gives no explicit guidance on when to use it over search_rooms or compare_rooms. It lacks when-not-to-use conditions or alternative mentions, so it is only minimally adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Most tools are distinct by resource and action, but the search/catalog cluster is fuzzy: search_universities, search_cities, list_search_metadata, and list_university_campuses overlap in purpose. search_rooms and rank_room_matches also have a similar discovery role, making it easy to select the wrong tool without careful reading.
All tool names follow a consistent snake_case verb_noun pattern, with verbs like add, list, get, search, create, update, and send clearly indicating the action. This makes the tool surface highly predictable and easy to navigate.
20 tools is on the heavier side, but the count is justified by the broad scope: room search, comparison, ranking, favorites, rental requests, messaging, listing creation, and university catalog browsing. The set remains manageable because each tool maps to a distinct workflow step.
Core room-finding workflows are covered well: search, details, compare, favorites, requests, and messages. However, listing management is incomplete (create_listing has no update/delete) and messaging only supports sending a first message, with no tool for replying to an existing conversation, leaving notable dead ends.