PropFácil

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

Annotations already indicate destructiveHint=true, and the description reinforces permanence ('permanently delete') and the cascading effect ('and its saved entries'). It adds context about authentication requirement, which is not in annotations. No contradictions found.

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

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

Two sentences, front-loaded with a clear directive, and no wasted words. Each sentence earns its place.

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

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

Given the tool's simplicity (1 parameter), strong annotations (destructive), and the presence of an output schema, the description is complete. It covers the essential usage and exclusions without needing additional details.

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 covers the parameter fully (description and constraints). The description adds the meaning of the parameter indirectly by mentioning ownership, but since schema coverage is 100%, the baseline 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 clearly states the tool deletes a favorite list and its saved entries, using specific verbs and the resource 'PropFácil favorite lists'. It distinguishes from sibling tools like 'remove_property_from_list' by explicitly saying not to use it for removing a single property.

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 explicit when to use ('when an authenticated user explicitly asks to permanently delete...') and when not to use ('Do not use it for removing a single property'). It also references the alternative tool implicitly by contrast.

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 establish readOnlyHint=true and destructiveHint=false, so the tool is known to be safe. The description adds that only authorized listings are accessible and that input must come from search_properties, which is useful behavioral context beyond 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 one concise, front-loaded sentence that gives the trigger condition, the input source, and the scope of the operation. There is no wasted wording 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?

Given the single parameter, complete schema coverage, safe read-only annotations, and presence of an output schema, the description covers all necessary context. It fully communicates what the tool does, when it applies, and what input is needed.

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

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

Schema coverage is 100%, and the schema already explains that 'id' is a listingKey or listing ID returned by search_properties. The description essentially repeats this schema information, adding no new 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 clearly states the tool retrieves details for one authorized PropFácil listing, using a listingKey or ID from search_properties. The verb 'get' plus the specific resource and prerequisite distinguishes it from sibling tools like search_properties or my_listings.

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 when to use the tool: when the user wants details for one listing and has supplied an ID from search_properties. It does not explicitly mention when not to use it, but the condition 'one authorized listing plus ID from search_properties' makes the usage context clear.

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 safety is covered. The description adds behavioral context by explaining that the tool enables contacting the advertiser or opening the original listing, which implies a navigation or disclosure action beyond a simple read. 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?

The description is a single, front-loaded sentence that states purpose and usage conditions without any fluff. Every phrase earns its place, 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?

The tool is simple (one parameter, read-only, with an output schema). The description provides the necessary context—when to use it and the property provenance requirement—and the output schema handles return values, so nothing additional is needed.

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 covers 100% of the parameter's meaning, describing 'id' as a listingKey or listing ID from search_properties or get_property. The description itself adds no parameter-specific details, so the schema carries the burden, meeting the baseline of 3.

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 specific action (contact advertiser or open authorized original listing) and the resource (property). It distinguishes itself from siblings like get_property (which retrieves property details) and search_properties (which searches) by specifying the exact trigger: 'when the user explicitly asks to contact the advertiser or open the authorized original listing.'

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 explicit usage context: 'when the user explicitly asks to contact the advertiser or open the authorized original listing' and restricts to 'a property previously returned by PropFácil.' It lacks explicit when-not-to-use or alternative tool references, but the trigger is unambiguous and the prerequisite is 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?

The description adds ownership and authentication context ('authenticated user', 'their ... favorite lists') and clarifies the return scope ('its saved properties'), which is useful beyond the annotations. It does not contradict the readOnlyHint and reinforces the non-destructive nature.

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 is tightly focused and front-loaded with the usage condition. It contains no filler or redundant restatement of the tool name.

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

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

Given the simple parameter set, the presence of an output schema, and informative annotations, the description is sufficient for an agent to select and invoke the tool correctly. It fully covers the essential context for a read-only single-resource lookup.

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 100% schema description coverage and only one parameter, the schema already documents listId clearly. The description adds little beyond what the schema states, so 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 clearly states the tool is for inspecting a single PropFácil favorite list and its saved properties, using a specific verb ('inspect') and resource. It distinguishes from siblings like list_property_lists, which lists lists, and get_property, which fetches a property.

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 to use it when an authenticated user wants to inspect one of their favorite lists and saved properties, which gives clear context. However, it does not explicitly name alternatives or state when not to use it, so it stops short of perfect guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to repeat those. It adds the scope detail that only lists owned by the linked user are returned, which is useful but not extensive behavioral context. It is minimal and does not contradict 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 two sentences, front-loaded with the invocation condition and the key constraint. Every word serves a purpose, with no filler or repetition of schema/annotations.

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

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

Given the tool's simplicity (no parameters, output schema present), the description is adequate. It covers the purpose, authentication context, and user ownership. It does not mention pagination or result count, but the output schema likely covers return structure, so this is 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 schema coverage is trivially 100%. Per rubric, 0 parameters gives a baseline of 4. The description does not need to explain parameters and does not attempt to.

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 'List their favorite lists' and 'returns only lists owned by the linked user', giving a specific verb and resource with user scoping. This distinguishes it from siblings like delete_property_list or search_properties.

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 'Use this when an authenticated user wants to see their PropFácil favorite lists', providing a clear trigger. However, it does not mention when not to use it or alternative tools, such as get_property_list for a specific list.

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, indicating a safe read operation. The description adds user scoping (authenticated user) and status (published) but does not disclose additional behavioral details like pagination or return format. This matches the calibration level where annotations cover the safety profile.

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 that is immediately actionable, with no filler or redundancy. Every word adds value.

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 an output schema, the description provides enough context to know when and how to use it, and it differentiates from siblings. It could mention limitations (e.g., only published listings) but that is already stated. The presence of an output schema means return values need not be explained.

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 (0 parameters), so the baseline is 4. The description correctly makes no parameter claims, and no additional parameter semantics are 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 states the tool lists property listings published by the authenticated user on PropFácil, using a specific verb 'review' and a clear scope. This distinguishes it from sibling tools like search_properties or list_property_lists, which have different purposes.

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 ('when an authenticated user asks to review the property listings they published'), but does not explicitly name alternatives or exclusions. The context is clear enough for an agent to select it over similar 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 it's not read-only and not destructive. The description adds valuable behavior: 'creates a public listing' and 'safe to retry with the same idempotencyKey,' clarifying idempotency semantics and public visibility. This goes beyond what the annotations provide, though it could have mentioned side effects like notifications or indexing. Satisfactory transparency.

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 concise sentences. The first sentence explains when to use it, and the second explains key behavior and idempotency. No unnecessary words, perfectly front-loaded. Excellent conciseness.

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 14 parameters, 6 required, and an output schema present, the description doesn't need to detail return values or every parameter. It covers the essential workflow trigger (user request) and a critical behavior (idempotent retry). It could have mentioned authentication requirements or conflict handling, but it's sufficiently complete for a tool 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?

The schema description coverage is 100% (all parameters have descriptions), so the baseline is 3. The description does not add parameter-specific details, but it doesn't need to, as the schema is comprehensive. No additional semantic value is provided for parameters, which aligns with 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 clearly states the action ('publish a property publicly') and resource ('property listing on PropFácil'). It distinguishes from sibling tools by focusing on the 'publish' action and the public listing aspect, which none of the siblings do. The specific verb 'publish' and context 'when an authenticated user explicitly asks' make the purpose 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 gives explicit context: 'when an authenticated user explicitly asks to publish a property publicly.' It clearly states when to use the tool. However, it does not explicitly list when not to use it or mention alternative tools (e.g., for editing an existing listing). This is a minor gap, but the context is clear and actionable.

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 indicate readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description adds that the list remains available if it becomes empty, which is a behavioral detail not covered by annotations. It also implies the operation is not destructive to the list itself, aligning with destructiveHint=false. No contradiction.

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-loaded with the primary use case, and includes a useful behavioral note about the list remaining available. No 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?

Given the tool's simplicity (2 params, no nested objects, output schema present), the description is complete enough. It covers the main use case, the authentication context, and a behavioral nuance. The output schema likely describes the return value, so the description doesn't need to. Slight gap: it doesn't mention what happens if the property is not in the list, but that's not critical.

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 explains both parameters: listId and propertyId. The description adds minimal extra meaning beyond the schema, but it does clarify that propertyId is a listingKey and that the list must be owned by the authenticated user. This is a baseline 3 since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: removing a saved property from a PropFácil list for an authenticated user. It uses a specific verb ('remove') and resource ('saved property from a list'), and it distinguishes from siblings like 'delete_property_list' (which deletes the entire list) and 'save_property_to_list' (which adds a property).

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 specifies when to use the tool: when an authenticated user asks to remove a saved property from a list. It implies the user must be authenticated, which is a key context. However, it doesn't explicitly mention alternatives or when not to use it, but the sibling tools are clear enough that this is the only removal tool for a property from a list.

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 this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds the auth requirement, which is useful context, but it doesn't disclose any additional behavioral traits such as side effects or response behavior. With annotations covering the safety profile, this is adequate.

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, and contains no filler or redundant information. Every word contributes to the purpose and usage context.

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 two-parameter rename tool, the description is complete enough. It specifies the auth context, the object being renamed, and the trigger. The output schema exists, so return values are documented separately. No critical gaps are apparent.

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 the meaning of 'name' and 'listId'. The description adds no parameter-specific information beyond what the schema provides. 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 clearly states the action (rename) and the resource (one of the user's PropFácil favorite lists). The sibling tools include delete, save, remove, and list operations, and 'rename' is unambiguous and uniquely distinguishes this tool from 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 explicitly provides a trigger condition ('when an authenticated user asks to rename') which tells the agent when to invoke this tool. It does not mention alternatives or exclusions, but for a simple rename operation the use case is evident and distinct from 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 description doesn't need to restate safety. It adds value by noting the tool renders interactive UI and by warning to pass only IDs from a data tool, which prevents hallucinated inputs. 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?

Two sentences, front-loaded with the key usage context and followed by a terse input constraint. Every word earns its place; no filler or repetition of schema 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 UI rendering tool with read-only annotations and an output schema present, the description fully covers when to use it, what it does, and the critical input guard. Nothing essential is missing given the tool's simplicity.

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

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

Schema description coverage is 100%, with propertyIds already described as 'listingKey values returned by search_properties' and title described. The description adds a similar caution about passing already-returned IDs, but this is largely redundant with the schema. 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 clearly states the tool's purpose: rendering property results as interactive cards, comparison, details, or a map after search_properties. It explicitly ties to the search context and distinguishes from data-fetching siblings like get_property and search_properties.

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 provides explicit when-to-use context (after search_properties, when user benefits from interactive UI) and a critical constraint (pass only listing IDs returned by a data tool). It does not explicitly mention when not to use, but the conditional framing implies it is not a substitute for search or data retrieval.

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 the trigger context but does not disclose edge cases (e.g., behavior when no previous selection exists) or any side effects beyond the restoration itself. It adds moderate 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?

The description is a single, clear sentence with no unnecessary detail or redundancy. It fully conveys the tool's purpose and condition without wordiness.

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 provides the main scenario and purpose. While it does not cover edge cases like absence of prior selection, the tool's simplicity and the existence of an output schema mean the description is adequately complete for its scope.

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 are zero parameters, and schema coverage is effectively 100%. According to the baseline rule for zero-param tools, a score of 4 is appropriate; the description does not need to explain 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 clearly states the action (restore), the resource (latest public property selection), and the context (current MCP session after widget recreation). It effectively distinguishes from sibling tools like search or get by targeting a session-specific restoration.

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

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

Explicitly provides the trigger condition ('after its widget is recreated') and context ('needs to restore the latest public property selection'). Does not mention alternatives or when not to use it, but the condition is clear enough.

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, so the write operation is implied. The description adds non-obvious behavioral context: the default list is idempotent and named 'Favoritos', which is valuable beyond the raw schema.

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

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

Two short sentences, no filler, and the trigger condition is front-loaded. Every phrase earns its place and the default-list rule is clearly stated.

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 4-parameter write action with an output schema and annotations, the description covers the key decision rule (default list fallback) and user context. It could elaborate on listId vs listName precedence, but the schema already documents these fields.

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 baseline is 3. The description adds meaning by explaining that when listId/listName are not supplied, the idempotent 'Favoritos' list is used, which clarifies the optional list parameters beyond the schema defaults.

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 verb 'save' applied to a property and the target 'favorite list', which directly distinguishes it from siblings like remove_property_from_list and get_property_list. It also mentions the default list behavior, making the tool's purpose 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?

It explicitly says 'Use this when an authenticated user asks to save a property to a favorite list' and provides the fallback rule for when no list is supplied. It does not explicitly name alternatives such as remove_property_from_list for removals, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, signaling a safe query. The description adds the scope 'authorized' and 'in Mexico', which is useful context, but it omits behavioral details like default ordering, pagination, or how results are returned—though an output schema exists. 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?

The description is a single, front-loaded sentence that immediately states the purpose and lists the main filters. It's concise and easy to scan, though it might be slightly more structured with explicit separators, but it earns a 4 for being tight and clear.

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 is a search with multiple optional parameters, the description covers the core use case but doesn't mention how filters can be combined, default behavior (e.g., if no filters are provided), or ordering of results. The presence of an output schema compensates for return details, but not for usage nuance. It's adequate but not exhaustive.

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 provides thorough descriptions for every parameter (100% coverage), so the description adds little beyond listing the filter categories. It repeats the filters already in the schema but doesn't clarify semantics like how 'near' works with radius or the currency for price. Since the schema is rich, the description doesn't need to repeat it, but it also doesn't add meaningful value beyond the trigger condition.

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 PropFácil property listings in Mexico, listing key filters (city, transaction type, price, bedrooms, radius). This sets a specific purpose, though it doesn't explicitly mention that it returns a list of matching properties.

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

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

'Use this when the user wants to find authorized PropFácil property listings' gives a direct trigger. It also enumerates the filter criteria (transaction type, price, bedrooms, radius), which guides when to invoke it. However, it doesn't contrast with sibling tools like render_property_results or get_property_list, so the selection logic isn't fully specified.

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