Lotlytics — US Real Estate Market Data & Investment Analytics

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

With no annotations, the description carries the full burden. It discloses an important prerequisite (API key with Investor plan) and describes the output format (head-to-head with winners). This adds meaningful behavioral context, though it doesn't explicitly mention that the operation is read-only or describe edge cases. Still, it provides more transparency than many similar tools.

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 exceptionally concise: four short sentences, each serving a distinct purpose (what, requirement, output, usage). It is front-loaded with the core action and contains no redundancy or fluff.

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 4 parameters, no annotations, and an output schema, the description covers the key contextual aspects: purpose, usage, prerequisite, and high-level output. The output schema handles the detailed return structure. The main gap is parameter semantics, but the description is otherwise well-rounded.

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 has 0% description coverage, so the description must compensate. However, it merely says 'Compare two real estate markets' without explaining how the four parameters (city_a/state_a, city_b/state_b) map to the two markets or any format/validation details. The parameter names are self-explanatory to some degree, but the description adds almost nothing beyond what the schema already shows.

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 the specific verb 'Compare' and clearly identifies the resource as 'two real estate markets side by side.' It further distinguishes itself from sibling tools by emphasizing the head-to-head nature and listing specific comparison dimensions (price, yield, appreciation), which is unique among the given siblings.

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

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

The description explicitly states when to use the tool: 'Use when deciding between two markets for investment.' This gives a clear decision context. It doesn't explicitly name alternative tools or when not to use it, but the intended use case is well defined and implies contrast with single-market or listing 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?

With no annotations provided, the description discloses the output format (score with label and key signals) and access limitations (top 50 markets free vs all 894 with API key). This goes beyond a simple read-only hint and covers useful behavioral context, though it does not detail what the key signals contain.

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

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

The description is three concise sentences, each adding distinct value: what it does, what it returns, and when/how to use it. No fluff 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?

The tool has a simple input schema (2 params) and an output schema, so return values are already structured. The description covers purpose, usage, and access constraints well. The only missing piece is explicit parameter format guidance, but overall the description is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. While the parameter names (city, state) are self-explanatory, the description does not specify expected formats (e.g., state abbreviation vs full name) or how they combine to identify a market. This is a notable gap for a tool relying on ambient 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 tool's function: getting a quick investment health score (1-10) for a US real estate market. It also distinguishes itself from siblings by noting it should be used FIRST for screening before using get_market_summary.

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

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

Provides explicit when-to-use guidance ('Use this FIRST for quick screening') and names an alternative tool for deeper analysis (get_market_summary). Also gives access tier context (free vs API key), which helps the agent decide if the tool is available.

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?

With no annotations, the description carries the burden of behavioral disclosure. It reveals what data is returned (median home price, appreciation, rental yield, momentum, migration) and discloses tier limitations (top 50 vs all 894 metros). It does not mention error behaviors or data freshness, but for a read-only getter it provides solid 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 extremely concise: three sentences that cover purpose, returns, tier limits, and usage guidance. It is front-loaded with the core action and avoids any filler 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 simple two-parameter schema and presence of an output schema, the description is complete. It covers what the tool does, what it returns, access tiers, and how it fits into the workflow. The agent has enough information to call and interpret the result without further external docs.

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 0%, so the description must compensate. It clarifies that the parameters refer to a 'US city or metro area', but does not specify the expected format for state (e.g., 'TX' vs 'Texas') or how to handle metro names. The names themselves are self-explanatory, but format details would improve semantic clarity.

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 function: 'Get a real estate market summary for a US city or metro area.' It distinguishes from siblings by specifying the full picture (returns median home price, appreciation, etc.) and explicitly contrasts with get_market_health for a quick score.

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 workflow guidance: 'Use get_market_health first for a quick score, then this for the full picture.' It also mentions tier constraints (free vs API key), giving clear when-to-use context. This is beyond basic and helps the agent choose appropriately.

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?

No annotations are provided, so the description carries the full burden. It discloses the tier-dependent behavior (50 vs. 894 markets), which is a key behavioral trait. But it omits other behavioral details like response format, pagination, or error handling, which would be valuable.

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 extremely concise: three short sentences that front-load the purpose. Every sentence adds valuable information without any filler.

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

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

Given the tool's simplicity and the presence of an output schema, the description covers all essential aspects: what it lists, tier limitations, and optional filtering. It is sufficiently complete for an agent to use it correctly.

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

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

The input schema has only one parameter, 'state', with no description. The description thoroughly explains it: 'Optionally filter by state (2-letter abbreviation or full name).' This adds clear meaning and provides valid input formats, fully compensating for the schema's lack of 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?

Clearly states the tool's function: 'List available real estate markets.' The verb 'List' is specific, and the resource is well-defined. Although it doesn't explicitly differentiate from sibling search_markets, the listing vs. searching distinction is clear.

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 clear context on when to use: free tier returns top 50 metros, API key expands to all 894 markets. This helps users understand the scope based on their access level. However, it doesn't explicitly mention alternatives like search_markets or specify when not to use the tool.

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?

No annotations exist, so the description carries the full burden. It discloses the API key requirement and default filter behavior, which adds value beyond the schema. However, it does not mention error handling, rate limits, readability, or response format, leaving some behavioral aspects untold.

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 concise and efficiently structured: purpose sentence, API key note, examples, filter list, and default behavior. Every sentence earns its place, and key information is front-loaded. No fluff 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?

The output schema exists, so return values are documented. The description covers purpose, usage examples, filter semantics, and default behavior. The only notable omission is the 'limit' parameter, but given the output schema and overall clarity, the description is sufficiently complete for a search tool.

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

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

Schema description coverage is 0%, but the description compensates by listing all main filters and providing examples that illustrate their meaning (e.g., 'under $300k' for max_price, '6%+ yield' for min_rental_yield). The description does not mention the 'limit' parameter, which is a small gap, but overall it adds significant semantic value.

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: 'Search for real estate markets matching specific investment criteria.' The verb 'search' and resource 'real estate markets' are specific, and the examples and filter list further clarify the scope. It distinguishes itself from sibling tools (e.g., list_markets) by emphasizing criteria-based search.

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 usage context through concrete examples ('markets in Texas under $300k with 6%+ yield') and notes default behavior ('No filters = top-ranked markets nationally'). It does not explicitly mention alternatives or when not to use the tool, but the context is strong enough that an agent can infer appropriate usage.

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