DealScanner

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

With no annotations, the description must convey behavior on its own. It discloses the either/or input structure and that the tool performs a BRRRR analysis. However, it doesn't specify what the analysis returns (e.g., cash-on-cash return, ROI) or what happens if both input modes are provided, leaving significant 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?

The description is two sentences, with the primary action front-loaded and the alternative input modes clearly separated. Every sentence provides necessary information without redundancy or 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?

The description covers the key input modes and parameter grouping, but lacks several contextual details: the output format or metrics of the analysis, error handling for missing/invalid inputs, and behavior when both `address` and raw inputs are supplied. Since there is no output schema, the absence of return-value information is a notable gap.

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

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

Schema coverage is 0%, so the description carries the burden for parameters. It names all five parameters and explains their roles: `address` for an existing listing, and `purchase_price`, `rehab_cost`, `arv`, `monthly_rent` as raw inputs. This grouping adds meaning beyond the schema's type-only definitions.

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: 'Run a BRRRR analysis.' It uses a specific verb and resource, and the expanded acronym 'buy-rehab-rent-refinance-repeat' adds clarity. The two input modes are mentioned, distinguishing it from sibling tools that focus on property data retrieval.

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 the two usage modes: provide an `address` for an existing listing, or provide the raw inputs for an ad-hoc deal. This gives clear context on when and how to invoke the tool. It doesn't explicitly name alternatives like `get_property` or `get_comps`, but the domain distinction 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?

No annotations are provided, so the description carries the full burden. It discloses the return categories and clarifies that stats are aggregated for a single area, but omits details like default behavior for area_type, error handling, or explicit read-only confirmation. The 'Get' verb implies non-mutating 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 two sentences plus an Args block, front-loaded with the primary purpose and returning a clear list of metrics. No redundant or unnecessary content.

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?

While the description covers the main purpose and parameters, it lacks detail on the exact return structure (e.g., what constitutes 'counts' or 'sold-comp metrics') and does not provide usage context relative to sibling tools. Given no output schema, this is a notable gap for an agent parsing results.

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 description provides semantic context absent from the schema: 'name' is described as a neighborhood or municipality with an example, and 'area_type' is constrained to 'neighborhood' or 'municipality'. This fully compensates for the schema's lack of field descriptions.

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

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

The description uses a specific verb ('Get') and identifies the resource ('aggregated market, sheriff, sold, and investment stats for one area'). It also clarifies scope ('for one area'), distinguishing it from sibling tools like top_investment_areas which likely cover multiple areas.

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 area-level aggregated stats are needed, and provides parameter guidance, but does not explicitly mention alternatives or conditions when not to use. No exclusionary or alternative tool references are given.

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 only explains parameters, not behavioral traits such as read-only nature, pagination, ordering, or other operational details.

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 minimal and to the point, with a clear purpose sentence and an organized Arg list. Every word earns its place without unnecessary 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 simple two-parameter query tool, the description covers the essential purpose and parameter semantics. It omits return format and edge cases, but given the low complexity, it is reasonably 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?

The description adds meaningful semantics to both parameters: 'query' is clarified as an address/area substring, and 'limit' is given a range (1-100). The schema itself lacks descriptions, so this is valuable.

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 ('Get') and a clear resource ('recently sold comparable properties'), making it distinctly different from siblings like get_property or search_deals. It unambiguously states what the tool does.

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 guidance is provided on when to use this tool versus alternatives. There are no explicit conditions, exclusions, or references to sibling tools in the description.

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?

There are no annotations provided, so the description carries the full burden of behavioral disclosure. It states that the tool 'gets' analysis, implying read-only behavior, but it doesn't confirm this or disclose any other behaviors such as error handling, rate limits, or what happens if the address isn't found. The description adds little beyond the purpose itself.

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 remarkably concise and front-loaded. The first sentence states the purpose, and the Args section is minimal but clear. Every sentence contributes value, with no wasted words or redundant 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?

For a simple two-parameter tool, the description covers the basic use case, but it lacks detail on the return format. Since there is no output schema, the description should explain what 'full DealScanner analysis' includes or how it is structured. It also doesn't mention error scenarios, leaving the context incomplete for an agent that needs to know what to expect in the response.

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 no descriptions (0% coverage), so the description must compensate. It explains 'address' as 'Full property address' and lists allowed values for 'strategy' (flip, rental, or brrrr). However, it doesn't explain what each strategy means or mention the default behavior when strategy is omitted, so the compensation is only partial.

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 what the tool does: 'Get the full DealScanner analysis for one property by street address.' This is specific with an action verb, resource, and scope, and it differentiates from sibling tools like get_comps or area_stats which presumably return narrower data.

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 you have a specific street address and want the full analysis. However, it doesn't explicitly mention alternatives or situations where a different tool would be more appropriate, leaving the usage guidance implicit rather than explicit.

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 transparency burden. It details parameter semantics and explicitly states the return shape ('dict with results, total, and pagination info'). It does not discuss permissions or side effects, but the search operation is inherently read-only, and the return contract is disclosed.

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 clean 'Args:' list with one line per parameter, followed by a one-line return summary. Every sentence adds information, there is no filler, and the structure makes parameters scannable.

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 9-parameter search tool with no output schema and no annotations, this description is remarkably complete: all parameters are documented, valid values are given, units are specified, and the return object is summarized. The only minor omission is exact pagination shape, but that is not essential for initial selection.

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 fully compensates by explaining every parameter: query matches address/municipality/neighborhood, strategy values, price bounds in USD, minimum beds/baths, comma-separated property classes, market vs sheriff source, and limit range (1-100). This is exactly the meaning an agent needs.

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 opens with 'Search DealScanner investment properties,' clearly stating the verb (search) and resource (DealScanner investment properties). The parameter list and sibling tool names (get_property, area_stats, top_investment_areas) show this is the listing-search tool, differentiating it from single-property or market-stats 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 description provides clear context for when to use this tool: when searching DealScanner investment properties by query, strategy, price, beds/baths, class, and source. It does not explicitly name alternatives or exclusions, but the sibling tool names make the use cases obvious, so it earns a 4 rather than 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?

With no annotations, the description carries the burden of behavioral disclosure. It transparently explains the sorting metrics, result format, and output fields, strongly implying a read-only query operation. Minor gaps like authentication or data freshness are not critical for this ranking tool.

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 well structured and compact, front-loading the purpose and then using Args/Returns sections to document parameters and output. Every sentence contributes actionable information without 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 no annotations and no output schema, the description fully compensates by covering the tool's purpose, parameter semantics, and expected return structure. An agent has enough information to invoke the tool correctly and interpret its results.

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 no descriptions, but the description fully covers both parameters: it lists all allowed values for sort_by with their meanings (including aliases) and the valid range for limit. This provides major value beyond the bare schema.

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

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

The description uses a specific verb ('Rank'), resource ('areas'), and scope ('neighborhoods + municipalities'), and directly answers a concrete user question ('where should I invest?'). It clearly differentiates from siblings by emphasizing market intelligence ranking rather than individual property analysis.

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 by stating it answers 'where should I invest?' using DealScanner's market intelligence. It does not explicitly name alternatives or mention when not to use it, but the intended use case 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?

With no annotations, the description carries the full burden. It discloses the core behavior (returning identity and scopes) but does not explicitly state that it is a read-only operation or describe any side-effect-free guarantee. The verb 'Return' implies read-only, but this is not made explicit.

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. Every word contributes to understanding the tool's purpose.

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

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

For a tool with zero parameters and no output schema, the description is nearly complete. It states what is returned (identity and scopes) and the principal type. While it doesn't detail the exact fields, that is acceptable for a simple whoami 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?

The tool has zero parameters, and the schema is empty with 100% coverage. The baseline for 0-parameter tools is 4, and no additional parameter explanation is needed. The description adds no parameter info, which is appropriate here.

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 clearly identifies the resource: 'identity and scopes of the current DealScanner API principal.' This unambiguously distinguishes it from sibling tools, which all focus on deal/property data rather than authentication context.

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 intended use is implied but not explicitly stated. There is no mention of when to use this over alternatives, though the tool's purpose ('whoami') inherently signals it is for identity/scope introspection. No exclusions or alternative references are provided.

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