UniAffitti Room Finder

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

Annotations already indicate this is a mutating, non-destructive operation. The description adds useful context—the room must be approved and the mutation applies to the authenticated user's own list—but does not disclose behavior around duplicates or failure when the room is not approved.

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, tight sentence with no wasted words. The verb, target, and key constraint are all front-loaded, making it easy for an agent to parse quickly.

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 simple single-parameter mutation with annotations and no output schema, the description is nearly complete. It conveys the action, the target, and the prerequisite. Idempotency or duplicate-handling details would be nice, but they aren't necessary for confident 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 0%, so the description must compensate for the lone room_id parameter. It adds the meaningful qualification that the room must be approved, but it doesn't explicitly map room_id to the room being saved or explain what counts as an acceptable value beyond the schema's minimum of 1.

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 verb ('Save'), a precise resource ('an approved room'), and a clear destination ('the authenticated user’s favorites'). This immediately distinguishes it from siblings like remove_favorite and list_my_favorites.

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: this tool is for saving rooms the user wants in their favorites, and only approved rooms are eligible. It doesn't explicitly mention alternatives or exclusions, but the intended use case is evident.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds that comparison includes specific attributes, but does not disclose return format, error behavior for invalid room_ids, or any additional constraints. With annotations covering the read-only nature, this adds moderate value but not rich behavioral detail.

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 sentence that leads with the action verb and immediately specifies the subject and comparison dimensions. Every word adds value, with no filler or repetition of schema information, making it highly concise and well-structured.

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 only 2 parameters, no output schema, and no nested objects, this is a relatively simple tool. The description covers the basic purpose and comparison scope, but omits details about the return format and the role of campus_id. While it is adequate for a simple comparison tool, it leaves some contextual gaps that would be useful for the agent.

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 0%, and the input schema only provides types and constraints, not meanings. The description clarifies that 'room_ids' refers to 'selected rooms' and implies the comparison fields, but does not mention the optional 'campus_id' parameter at all. It partially compensates for the lack of schema descriptions but leaves a key parameter semantically undocumented.

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 verb ('Compare') with a clear resource ('selected rooms') and lists the comparative dimensions (price, distance, type, availability, features, trust signals). This clearly distinguishes it from siblings like get_room_details (single room) and rank_room_matches (ranking), so the purpose is unambiguous.

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

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

The description implies when to use this tool: when multiple rooms are already selected and need side-by-side comparison. It does not explicitly name alternatives or exclusions, but the context of 'selected rooms' and the comparison focus makes the usage context clear relative to siblings like search_rooms.

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

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

Annotations already indicate a write operation, but the description adds valuable behavioral context: the listing is only a draft, it is subject to moderation, and university_id/campus_id are intentionally kept NULL. This goes beyond the schema and annotations, helping the agent understand the side effects and data model.

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

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

The description is two sentences, front-loads the core action, and adds one crucial non-obvious detail. There is no filler or repetition of schema information.

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

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

With 18 parameters, a nested object, no output schema, and minimal schema descriptions, the description is too sparse to fully prepare an agent. It does not explain moderation workflow, expected response, or the semantics of key parameters beyond a generic listing creation context.

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 only 11%, so the description carries a heavy burden for explaining parameters. It does not explain the meaning or expected format of most of the 18 fields, apart from the location-independence concept. The description does not compensate for the sparse schema 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 uses a specific verb ('Create') and resource ('UniAffitti listing draft for moderation'), making it clear that this is a creation tool rather than a read or request tool. It also distinguishes this from create_rental_request by stating the result is a listing draft, not a request.

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 creating listings that will be moderated, so an agent can infer when it applies, but it does not explicitly state when to avoid it or compare it to siblings like create_rental_request. The note about university_id and campus_id being intentionally NULL provides some operational guidance, but not explicit routing.

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

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

Annotations only indicate that this is not read-only and not destructive, so the description adds meaningful context by specifying the authenticated account requirement and the eligibility precondition of an approved available room. It does not contradict the 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 a single concise sentence that front-loads the core purpose and adds the key precondition and authentication context without wasted words.

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, and the description does not explain expected return behavior, side effects, or parameter semantics. For a tool with four parameters and one required field, the description is too thin for an agent to invoke it confidently in varied scenarios.

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 only 25%, and the description does not compensate by explaining message, start_date, duration_months, or room_id beyond the generic notion of a room. The agent is left without meaningful guidance for the majority of parameters.

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 action ('Send a rental request') on a specific resource ('an approved available room') and names the authenticated account context. This clearly distinguishes it from sibling tools like list_my_requests or update_rental_request_status.

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

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

The description implies when to use the tool by requiring an 'approved available room,' which gives useful context. However, it does not explicitly name alternatives or state when not to use this tool versus related siblings like update_rental_request_status.

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

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

Annotations already declare the operation read-only and non-destructive. The description adds useful context about which areas the links cover, but it does not describe the exact return structure, whether the links are absolute URLs, or any authentication context. With annotation coverage present, the added behavioral detail is adequate but not rich.

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 sentence, front-loaded with the action ('Return deep links'), and every phrase adds meaning by enumerating the target account areas. There is no redundant or filler wording.

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 link-retrieval tool, the description gives enough context: the agent knows exactly what is returned and which areas are covered. The only minor gap is that the return format itself is unspecified, but the absence of an output schema and the simplicity of the tool make this acceptable.

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 has zero parameters, so the input schema already exhaustively covers invocation needs. Per the baseline rule for 0-parameter tools, the description does not need to add parameter-level detail. No parameter ambiguity exists.

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 verb ('Return deep links') and names the exact resources covered: account, listing creation, messages, requests, and favorites. It clearly distinguishes this from the data-returning sibling tools such as list_my_favorites or get_my_profile. The scope is unambiguous.

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

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

The description implies when to use this tool: when the agent needs deep links into those account areas in the full web app, rather than retrieving data directly. However, it does not explicitly state exclusions or mention alternatives, leaving some inference to the agent. A clear usage note versus sibling data tools would have made this stronger.

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

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

Annotations already convey read-only/non-destructive behavior, and the description adds the 'data-only' and 'authenticated' context, which is useful but not substantial. It does not disclose ordering, pagination, or whether messages are marked read, so it stays at a solid mid level.

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 focused sentences with the action and the intended caller front-loaded. Every clause earns its place; no filler or redundant restatement 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?

For a simple read-only tool this is nearly complete: it names the resource, the caller, and the data-only nature. It would be complete with one sentence about message ordering/pagination or where conversation_id comes from, but those are minor 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?

The schema already documents conversation_id as a Firebase conversation/thread id and messages_limit with default/min/max constraints. The description's 'recent messages' weakly reinforces the role of messages_limit but adds no concrete parameter guidance, so it does not go beyond the baseline.

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

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

The description uses a specific verb ('Load') and a bounded resource ('recent messages for one authenticated UniAffitti conversation'), and the title reinforces it. It clearly distinguishes a single-conversation read from siblings like list_my_messages and send_room_message.

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

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

It gives clear intended context: called by the messages UI after the user selects a conversation. It does not explicitly name alternatives or when-not-to-use conditions, so it misses the top tier.

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

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

Annotations already indicate readOnly and non-destructive behavior. The description adds valuable context by disclosing that the tool initiates OAuth when unauthenticated and returns the profile without credentials or secrets, which goes beyond the annotation information.

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 well-structured sentence that front-loads the trigger condition and then explains the authentication behavior and return value. Every clause earns its place with no redundancy.

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

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

For a zero-parameter tool with no output schema, the description sufficiently explains when to call it, what side effects may occur, and what is returned. It could be slightly more explicit about the shape of the returned profile, but the core information needed to invoke it correctly is present.

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 has zero parameters, and schema description coverage is 100%, so there is no parameter documentation burden. The description appropriately avoids unnecessary parameter detail.

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

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

The description clearly states the tool returns the user's profile and handles OAuth authentication, which is a specific action on a clear resource. It is distinguishable from siblings like get_account_links, though it does not explicitly contrast itself with them.

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

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

The description provides a clear trigger condition: call this tool when the user asks to access or connect UniAffitti. It gives useful context about the authentication flow but does not explicitly mention when not to use it or name alternative tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context about the response scope ('public details', 'limited landlord trust information') and the constraint 'approved room,' which goes beyond the bare annotations. It does not contradict any annotation.

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

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

The description is a single sentence that front-loads the action and resource, then lists the key content categories. No extraneous words or redundancy.

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

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

For a simple one-parameter read-only tool, the description covers purpose, constraints, and return content. Combined with strong annotations and clear sibling context, it is sufficiently complete without needing additional details like error handling.

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?

There is one parameter (room_id) with 0% schema description coverage. The description implies that the ID should correspond to an approved room, but provides no further detail about the parameter itself. This gives marginal compensation but relies heavily on the parameter name and tool name for meaning.

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 verb ('Return') and identifies the resource ('public details for one approved room'), clearly distinguishing it from sibling tools like search_rooms or compare_rooms. It also lists the content categories (media, features, trust info), making the purpose unmistakable.

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 usage when a specific room's details are needed, with the constraint 'approved room.' However, it does not explicitly state when not to use it or name alternatives. The context is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is known. The description adds the ownership and availability scoping, but does not mention potential behaviors like filtering, ordering, or pagination. With annotations covering the safety profile, this is adequate but not rich.

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 that conveys the exact resource and scope with no filler. Every word contributes meaning.

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 no-parameter, read-only listing tool with safety annotations present, the description is largely complete. It does not describe the return payload, but no output schema exists and the operation is simple enough that the absence is not a major 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?

The tool has zero parameters and schema coverage is 100%, so there are no parameter semantics to clarify. The description correctly implies the operation requires no explicit arguments beyond authentication context.

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 action ('List') on a specific resource ('the authenticated user’s saved available rooms'). It is clearly distinguished from sibling tools like list_my_listings and list_my_requests, which target different resources.

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 makes clear this is for viewing the user's own saved favorites, not all rooms or search results. It does not explicitly name alternatives or exclusions, but the scope is unambiguous and contextually sufficient.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that the result includes moderation status, but it does not disclose return format, pagination, or error behavior. With the safety profile already carried by annotations, a 3 matches the calibration of simple read tools that lack richer behavioral context.

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

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

The description is a single sentence with no filler or redundancy. The core action and resource are front-loaded, and every word contributes to the tool's meaning.

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 annotations covering safety, the description is largely complete for invocation. It names what is returned (listings and moderation status), though with no output schema it leaves the exact response shape unspecified. That is a minor gap, not a blocker 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?

The input schema is empty with no properties, so there are no parameter semantics to explain. The description's phrase 'authenticated user’s own' clarifies that the data source comes from the auth context rather than an input parameter, which is sufficient given 0 parameters.

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 ('List'), a clear resource ('the authenticated user’s own listings'), and adds 'moderation status' to specify the output content. This clearly distinguishes it from sibling tools like list_my_favorites, list_my_requests, and search_rooms.

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 unambiguously scopes the tool to the authenticated user's own listings, so an agent can tell when to invoke it (e.g., 'show my listings') versus using a general search or another 'my' list. It does not explicitly name alternatives or exclusions, but the context is clear enough for selection.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds genuine behavioral value on top: the dual-mode response behavior (summaries/previews vs. complete recent messages) and the web-app data-source context. No contradictions with the 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?

Two sentences with zero filler. The purpose is front-loaded in the first sentence, and the conditional behavior occupies the second. Every clause earns its place, with no restatement of the title or 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?

For a tool with four optional parameters, no required parameters, and annotations covering safety, the description captures the core dual-mode behavior and even hints at return content (summaries/previews vs. full messages). The main omission is the unread_only filter's semantics, and with no output schema present, some return-shape expectations are left to inference.

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 only 25% (only conversation_id is documented). The description compensates for conversation_id by explaining it triggers the full-message mode, and loosely implies limit/messages_limit via 'fast summaries' vs. 'complete recent messages.' However, unread_only is never mentioned in either the schema or the description, leaving a real gap.

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

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

The description uses a specific verb and resource — 'Read the authenticated user's UniAffitti conversations' — and adds a useful scoping detail, 'from the same chat used by the web app.' It clearly distinguishes from list_my_favorites/list_my_listings/list_my_requests by resource and from send_room_message by read-vs-write verb, though it never names a sibling 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 gives strong conditional usage context: 'Without a conversation_id return fast conversation summaries and last-message previews; with one load the complete recent messages for that conversation.' This tells the agent exactly what to expect in each mode, but it does not explicitly state when to prefer this over send_room_message or other siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful scope context ('sent or received by the authenticated user') but doesn't disclose potential behavioral details such as output format, sorting, limit, or pagination. This is adequate but not rich.

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 one concise sentence with no wasted words. It front-loads the verb and resource, then adds the essential user-scope detail. Every part 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?

Given the simplicity of the tool, one optional parameter, and annotations that establish safety, the description is almost complete. It leaves out response format and pagination behavior, which would be helpful but not critical for a straightforward list operation.

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?

There is only one parameter, direction, and the schema provides an enum and default. The description's phrase 'sent or received' maps to two enum values and gives some semantic context, but the description doesn't explicitly explain that direction filters results or that 'all' is the default. With 0% schema description coverage, this is only partial compensation.

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 verb ('List'), identifies the exact resource ('rental requests'), and scopes it to the authenticated user ('sent or received'). This clearly distinguishes it from sibling tools like create_rental_request, update_rental_request_status, list_my_listings, and list_my_favorites.

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 makes the use case clear: call this when the goal is to retrieve rental requests involving the current user. It doesn't explicitly name alternatives or state exclusions, but the resource type and user scope are enough to route an agent correctly among the listed siblings.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds meaningful behavioral context: the response is a paginated slice, the catalog is global, and it is not artificially capped at 500 records. It does not cover output shape or filter interaction, but it goes beyond what annotations provide.

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 no filler, and the core list/pagination action is front-loaded. The phrase 'optional campuses, and feature filters' is grammatically awkward and slightly unclear, which keeps it from 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?

The description gives enough to make a valid call since all parameters are optional and the read-only nature is declared, but it does not describe the returned shape of campuses or feature filters, and there is no output schema to fill that gap. The interaction between country/query filters and the returned metadata is also left unexplained.

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 50%; university_query and university_country_code are already described in the schema, while university_limit and university_offset lack descriptions but are semantically obvious from names and defaults. The description adds the 'paginated slice' framing but does not compensate for the missing parameter descriptions or explain how filters affect the returned metadata.

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 a list operation over the global university catalog and related campuses/feature filters for room search, which distinguishes it from a generic 'search' tool. It is slightly ambiguous about what 'optional campuses, and feature filters' means grammatically, but the resource and action are identifiable.

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?

No explicit when-to-use guidance is provided, and the sibling tool search_universities could plausibly overlap. The only indirect usage hint is 'The catalog is not limited to 500 records,' implying this tool is for paginated full-catalog access, but no alternatives or exclusions are named.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the 'active' filter and the dependency on a selected university, providing useful behavioral context beyond the annotations. It doesn't disclose return shape or ordering, but those are less critical for a simple read-only list.

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?

Single sentence, front-loaded with action and scope, with a clear purpose clause. No filler or repetition of the title 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 one-parameter, read-only list tool, the description is sufficient: it tells what is listed, the active filter, and why it is called. Annotations cover safety, and no output schema is present but the name and description imply a list of campuses. Missing pagination and field details are minor in this low-complexity context.

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?

With 0% schema description coverage, the description must carry parameter semantics, and it partially does by saying 'for a selected university,' linking university_id to a prior selection. It doesn't spell out that the ID should come from search_universities, but the single integer parameter is straightforward and the description gives enough context.

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 verb ('List') and resource ('active campuses for a selected university'), and ties it to a concrete workflow step ('refine the room search'). This clearly distinguishes it from sibling tools like search_universities or search_rooms.

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

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

It states the tool is used after a university has been selected and for the purpose of refining a room search, giving clear context. It doesn't explicitly name alternatives or exclusions, but no sibling tool overlaps with listing campuses.

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

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

Annotations already declare readOnlyHint=true and 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.

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

The destructiveHint annotation already signals destructive behavior, and the description aligns with it. The description adds a useful scoping detail: the operation affects the authenticated user's favorites, not a global list. It does not disclose whether the removal is permanent, idempotent, or what happens when the room is not already a favorite.

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. Every word contributes meaning, and it avoids restating the annotation or schema details. It is appropriately sized for a simple one-parameter operation.

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?

This is a simple tool with one parameter and annotations that signal destructiveness, but there is no output schema and no guidance on edge cases such as removing an already-absent favorite or whether the operation is reversible. The description is adequate but incomplete for an agent that needs to handle error cases confidently.

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 provides only the type and minimum for room_id, with 0% description coverage, so the description needed to compensate. It does not explicitly explain that room_id identifies the saved room to remove or that it must reference a current favorite of the authenticated user. The mapping is only implied by the tool name and sentence structure.

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 action ('Remove'), a specific resource ('a room'), and a specific scope ('the authenticated user's favorites'). This clearly distinguishes it from sibling tools like add_favorite and list_my_favorites. The verb and resource are unambiguous and match the tool name and title.

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

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

The description provides clear context: this tool removes a favorite for the authenticated user. However, it does not explicitly name alternatives or state when not to use it, leaving the usage distinction implied rather than explicit. It is still clear enough for an agent to infer the correct scenario.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful scope context ('complete active worldwide catalog') and notes that results include country and university counts, but it does not disclose return structure, pagination, or sorting 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?

The description is a single front-loaded sentence that wastes no words. It starts with the action and resource, then adds the key distinguishing output detail, making it easy to scan.

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 search tool with four optional parameters, no output schema, and no parameter documentation, the description is too thin. It fails to explain expected return shape, filtering semantics, pagination, or how the counts are structured, leaving an agent without the information needed to call the tool effectively.

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 0%, and the description provides no parameter-level guidance. It does not explain what 'query' matches, how 'country_code' filters, or how 'limit' and 'offset' behave. The description's mention of 'country and university counts' hints at output aggregation, but not at parameter semantics, so it fails to compensate for the schema gap.

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

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

The description names a specific verb ('Search'), a concrete resource ('cities in the complete active worldwide university catalog'), and adds a distinguishing output detail ('country and university counts'). This clearly differentiates it from the sibling search_universities and search_rooms 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 'for assisted room search' implies the tool is meant for a pre-room-search filtering step, giving some contextual usage guidance. However, it does not explicitly state when to use this versus search_universities or search_rooms, nor does it name any exclusions or alternatives.

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

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

Annotations already cover the read-only safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds the valuable behavioral trait that results are restricted to 'approved and available' rooms. It does not disclose pagination behavior, default ordering (order_by defaults to 'newest'), or that filters are all optional, leaving some behavioral gaps.

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 sentence with zero wasted words, front-loaded with the verb and resource before listing filter dimensions. It is efficiently structured, though for a tool of this complexity (14 params), it is lean enough that some information is sacrificed.

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 14-parameter tool with only 29% schema coverage, no output schema, and a nested features object, the description is not sufficient on its own. It omits pagination semantics (offset/limit), sorting behavior, and the structure of the features filter. The description is an adequate high-level summary, but an agent needs to inspect the schema carefully to invoke all capabilities correctly, and several params remain undocumented in both schema and description.

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?

With only 29% schema description coverage, the description partially compensates: 'budget' maps to min_price/max_price, 'type' to room_type, 'university' to university_id, 'campus' to campus_id, 'distance' to max_distance_km, and 'features' to the features object — all of which lack schema descriptions. However, it leaves limit, offset, order_by, and other params semantically unexplained, and does not clarify that the features parameter is a nested filter object.

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 verb ('Search'), a clear resource ('approved and available student rooms'), and enumerates the key filter dimensions (budget, type, university, campus, distance, features). The 'approved and available' qualifier adds useful scope beyond the tool name. However, it does not explicitly differentiate from siblings like get_room_details, compare_rooms, or rank_room_matches, though the resource type inherently sets it apart from search_cities and search_universities.

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 is the tool for filtering student rooms by criteria, which is enough to infer basic usage. It does not explicitly state when to prefer alternatives (e.g., get_room_details for a single room, compare_rooms for side-by-side comparison) or mention exclusions. The absence of required parameters suggests unconstrained search is possible, but this is not stated.

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

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

Annotations already mark this as read-only and non-destructive. The description adds useful behavioral context by stating the catalog is 'active' (inactive entries excluded), 'worldwide', and that results support pagination and total count. This goes beyond the structured annotations without contradicting them.

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

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

The description is a single focused sentence with no redundancy. It front-loads the core action and resource, then adds the key behavioral notes. Every word 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?

The description is too sparse given the lack of an output schema and 0% parameter coverage. It does not explain what the response contains, how filters combine, or what formats are expected (e.g., country_code). An agent would have to guess at parameter semantics and return structure, so the description is not complete enough for reliable 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 0%, so the description must compensate for the five parameters. It does not explain query, city, country_code, limit, or offset semantics. The mention of pagination only vaguely hints at limit/offset, leaving parameter meaning almost entirely to inference from names.

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 action ('Search'), the resource ('complete active UniAffitti university catalog'), and the scope ('worldwide'). It also distinguishes this tool from siblings like search_rooms, making the intended target unambiguous.

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

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

The description implies the tool is for searching universities globally, and the resource name separates it from room search tools. However, it does not explicitly state when to use it over alternatives or mention any exclusions or preconditions, leaving usage somewhat implicit.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds meaningful behavioral context beyond annotations by specifying that the conversation is stored in the same UniAffitti chat used by the web app, and that the action originates from the authenticated account.

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

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

The description is two tight sentences with no filler. It front-loads the core action immediately and adds the storage detail as a second sentence, earning every word.

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?

The description covers the essential context: the action, the target, the precondition, authentication, and persistence. There is no output schema and no return-value description, but for a simple send-message tool the description is nearly complete.

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 0%, so the description needs to compensate by explaining room_id and message. It does imply that room_id refers to an approved available room and message is the first message content, but it never explicitly maps or describes the parameters, leaving much of the semantics to inference from property names.

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 sends a first message to the landlord of an approved available room. It further narrows the scope with the authenticated UniAffitti account and the approved/available preconditions, making it clearly distinct from sibling tools like get_room_details or create_rental_request.

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 'first message' and 'approved available room' gives clear context for when this tool should be used. It does not explicitly name alternatives or state when not to use it, but the intended scenario is unambiguous enough for an agent to select it correctly.

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

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

Annotations already mark this as not read-only and not destructive, so the mutation nature is expected. The description adds role-based authorization context but does not disclose transition rules, side effects, or response behavior. It adds some value beyond annotations without contradicting them.

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

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

The description is a single, front-loaded sentence with no filler. Every phrase earns its place, with the key status verbs first and the role constraint at the end.

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 simple status-update tool with no output schema, the description is mostly adequate, but it omits conditional details like the need for available_from when accepting (though present in the schema) and specific role-to-status mappings. An agent could call it correctly in common cases, but edge cases like accepting without available_from may be missed if relying on the description alone.

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?

With only 33% schema description coverage, the description bears some responsibility for parameter meaning. It maps the status enum to human actions ('accept, review, reject, cancel') but does not explain request_id semantics or explicitly mention that available_from is required when accepting, though the schema does. The name and enum make request_id fairly self-evident, so the description provides moderate compensation.

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 verb ('Accept, review, reject, or cancel') and a specific resource ('UniAffitti rental request'), making the tool's purpose unmistakable. It clearly distinguishes itself from read-only and create siblings like list_my_requests and create_rental_request. The role-based clause adds useful 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?

The description conveys a clear context: an authenticated user changing a rental request status subject to their role. It does not explicitly name alternatives or state when not to use the tool, but the action is specific enough that an agent can infer when it applies. No misleading guidance is present.

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