Small Business Intelligence by Brick & Mortar

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

Annotations already declare readOnly/destructive/openWorld, but the description adds non-obvious traits the annotations can't convey: it's free with no account, the document is 'read in the request, answered, and dropped — nothing is stored on either side', and the caller should confirm in one line what was sent and that it wasn't kept. The idempotentHint=false annotation is not addressed, but nothing contradicts the stated 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?

Front-loads the core action and the operational instructions are tight, but it spends a sentence on pitch/marketing ('their private file, our joined records, one answer') that doesn't help an agent invoke the tool. The example invocations earn their place; the sloganeering does not.

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?

An output schema exists, so return values need not be explained, and the description covers the privacy lifecycle, cost, required slug discovery, and the text-vs-claim branch. For a 4-parameter tool with a nested `context` object, the remaining gap is that the `context` sub-fields (fromMonth, radiusFeet, subjectAddress) are only explained in the schema and tied to 'tools that ask since when' in the description only loosely.

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 75% schema coverage the schema carries most parameter detail, but the description adds material routing semantics: `tool` is not an enum and must be sourced from what_we_have_for_you, `claim` replaces `text` for 'claim-check', and text must be passed verbatim ('do not summarise a P&L before sending it'). The `context` sub-fields are left to the 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?

States a specific verb+resource (reads a person's document against the Minneapolis–St. Paul public record) and a concrete output (a table that cites the file behind every cell). It also positions itself against the public-record-only siblings by framing itself as 'the half of the platform the public record cannot do alone', so an agent can distinguish it from twin_cities_lookup/twin_cities_records.

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?

Gives a clear invocation prerequisite ('Get the slug and what to bring from what_we_have_for_you', cards with api_tool=true list `bring`) and three worked example invocations mapping real-world asks to the `tool` slug. It doesn't state when NOT to use it (e.g. when the data is already public and twin_cities_lookup suffices), so it stops short of full when/when-not 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?

The description adds meaningful behavioral detail beyond the readOnly/idempotent annotations: it states the model must research category multiples fresh and date-stamp them, explicitly rejects hardcoded tables, and specifies that the red-flag checklist runs before financials are shared and seller questions are built from research gaps. This gives the agent a clear picture of the tool's internal process and constraints.

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 dense but well-organized: a lead sentence enumerating the four framework components followed by four example invocations. The examples earn their place by clarifying acceptable request phrasings, though the opening sentence is heavy with parentheticals and could be tightened without losing 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 tool of this complexity, the description covers purpose, deliverables, behavioral constraints, and practical invocation examples, while the output schema handles return-value expectations. An agent has everything it needs to decide whether to call this tool and how to phrase the request 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 already provides 100% coverage for all four parameters, so the baseline is 3. The description adds illustrative context by showing concrete city_metro formats ('Minneapolis, MN', 'Wichita, KS'), asking_price examples ('$650K', '$310K'), and how category and asking_price are used for sanity-checking against multiples, which helps an agent formulate effective calls.

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 identifies a pre-diligence framework with four concrete deliverables: SDE framing, a category multiple range, a red-flag checklist, and a prioritized seller-question list. The example invocations show exactly what the tool does, making it easy to distinguish from siblings like business_teardown or market_opportunity_scan.

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 example invocations establish clear usage contexts: preparing for diligence on a specific business, asking seller questions before an offer, checking red flags before taking an asking price seriously, and sanity-checking against category multiples before meeting the seller. It does not explicitly name sibling alternatives or state when not to use the tool, so it falls just short of full routing 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?

Adds behavior that annotations cannot express: the tool returns a framework, not the finished analysis, it fetches no data itself, and the calling model must run the procedure with its own web search. This is consistent with (and adds meaning to) readOnlyHint=true and openWorldHint=false rather than 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 key insight — framework, not analysis — is front-loaded in the first clause, and the no-data-fetch caveat follows immediately. The three example invocations are useful but slightly pad the length, and a stray double period ('question..') is a minor blemish.

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 an output schema present, return-value detail is unnecessary, and the description covers the framework nature, the no-fetch behavior, and entry conditions. It could say more about when to graduate to sibling tools, but nothing needed to call it correctly is missing.

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% and each parameter (business_name, city_metro, category) is already well documented in the schema, including the caution not to guess the category from the name. The description adds only the 'one named business' scoping constraint, so the baseline 3 applies.

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?

States a specific deliverable — a research framework (procedure, output schema, quality rubric) for a structured teardown of ONE named small business — and enumerates the covered dimensions (digital presence, review signal, competitive position, pricing, visibility gaps, recommendations). The scope word 'ONE' implicitly separates it from multi-business siblings like competitor_landscape and market_opportunity_scan.

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?

'Start here for any single-business question' gives a clear entry condition, and the three example invocations show the intended shape of a request. It never explicitly names which sibling to use instead for multi-business or benchmark questions, so routing is inferred rather than 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 cover the safety profile (readOnly, non-destructive, idempotent, closed-world), so the bar is lower. The description adds genuinely important behavioral context that annotations cannot convey: 'This tool fetches no data; the calling model runs the procedure with its own web search and produces the result,' which tells the agent this returns instructions, not data. It stops short of describing how large the returned procedure is or how the result should be structured back.

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 key framing ('framework, not finished analysis') is front-loaded in the first sentence, which is exactly right. Three worked examples are helpful but slightly redundant, and a stray double period ('saturation signals..') is a minor polish issue.

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 an output schema present, the description is not obligated to explain return values, and it correctly focuses on the unusual behavioral contract instead. Combined with annotations and full schema coverage, an agent has enough to invoke it correctly, though a note on how the resulting analysis should be handed back would make it fully self-contained.

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 category, city_metro and radius_note with examples. The description adds no format, constraint, or edge-case detail beyond what the schema provides, making the baseline 3 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 states a specific verb and resource — it returns the procedure, output schema and quality rubric for mapping a local competitive set for a category + metro — and explicitly frames what the tool is not ('Returns a research framework, not the finished analysis'). This distinguishes it from siblings like market_opportunity_scan and pricing_benchmark without needing their schemas.

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 clearly states the context of use — mapping true competitors vs. adjacent players with positioning and saturation signals — and the example invocations show the intended shape of requests. However, it never explicitly says when to pick this over a sibling such as market_opportunity_scan or local_visibility_audit, so the routing guidance is implicit rather than 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 declare readOnly/idempotent/non-destructive/non-open-world, so the safety profile is covered. The description adds the non-obvious behavioral trait that this tool is a pure structural no-op that fetches nothing and returns only a framework, with the calling model doing the actual writing — real context beyond the annotations. It omits auth/permission requirements, so not a 5.

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?

Purpose is front-loaded in the first clause and the example invocations are genuinely useful. However there is redundancy — 'the calling model writes the report; this tool returns only the structure' and 'This tool fetches no data; the calling model runs the procedure' restate the same point — plus a stray double period ('structure..').

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 an output schema present, return values need no explanation, and the description still covers what the tool is, what it does not do (fetch data), when to call it, and the audience-driven behavior. Nothing an agent needs in order to invoke it correctly is missing.

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 audience, business_name, and completed_analyses, including the 'not re-researched' note. The description reinforces intent ('results already in the conversation') but adds no format or syntax detail beyond what the schema provides, matching the baseline 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?

States a specific verb+resource (compose a report) and precisely delimits it: 'Returns a research framework, not the finished analysis' and it 'returns only the structure.' It explicitly separates itself from the sibling analysis tools by declaring it fetches no data, so an agent can distinguish it from business_teardown, review_intelligence, etc.

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 three example invocations clearly show the intended usage context (assembling prior analyses for a specific audience), and the text states the inputs must be 'completed write-ups from any prior tool calls this session, to be assembled — not re-researched.' It implies the prerequisite (run the analyses first) but never names a specific alternative tool for the analysis step, so it stops short of explicit when-not/alternative 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the output is an advisory plan rather than data, it will explicitly declare 'what the public record cannot answer at all', and it accepts an already_tried input to avoid dead-end re-recommendations. No return format is given, but an output schema exists, so that omission is defensible.

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?

Front-loaded with the core statement, with the usage directive second and examples last, which is the right ordering. The parenthetical source list ('county parcel GIS, Census CBP/ACS/permits, BLS series...') is dense, and the run-on opening sentence is long, but nothing is wasted for a tool whose value is conceptual framing.

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?

An agent has everything needed: all three parameters are documented at 100% coverage, an output schema handles the return shape, annotations cover the safety profile, and the description supplies the conceptual framing plus worked examples. There is no obvious gap an agent would hit before invoking it.

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 and the schema carries parameter documentation. The description still adds value by showing four concrete example invocations that demonstrate what a well-formed question and place look like, and the schema itself goes further by explaining that state choice determines whether sale prices exist. Modest but real lift over the structured fields.

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 — 'returns a source-first RESEARCH PLAN' — and immediately enumerates what the plan contains (which record settles the question, how to reach it, what it's worth, what it cannot answer). This decisively separates it from data-returning siblings like twin_cities_records or twin_cities_lookup, which fetch records rather than routing to 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?

It gives a clear temporal/contextual trigger: 'Use it before researching a local market, to find the administrative record that settles the question.' That is genuine when-to-use guidance. It stops short of naming alternatives or stating when NOT to use it (e.g. when you already know the dataset and should call twin_cities_datasets directly).

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, idempotentHint and non-destructive, but the description adds the non-obvious core behavior: it returns a framework, not a completed audit, reads no listing, and the calling model is expected to run the checks itself. That is exactly the kind of contract an agent cannot infer from 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 most important caveat — that this is a framework, not an audit — is front-loaded in the first sentence, followed by compact domain enumeration and three tightly written example invocations. No sentence is 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?

With an output schema present, return values need no explanation, and the description covers the one behavioral fact an agent must know (it produces a checklist rather than reading listings). Nothing needed to call it correctly is missing.

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 each parameter is already documented in the schema. The description only lightly reinforces this by implying the category narrows which map-pack searches matter, adding no syntax or format detail beyond the schema. Baseline 3 applies when the schema carries the load.

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?

States a precise verb and resource: it 'returns a research framework... a scored checklist' covering named domains (map-pack factors, listing consistency, category selection, site fundamentals). The framing 'not the finished audit' sharply defines what the tool is. It does not name or contrast any specific sibling tool, so it falls 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 example invocations clearly map real query shapes to this tool, and the line 'This tool reads no listing; the calling model runs the checks with its own web search' tells the agent when this is the right call versus actually fetching data. However, it never names an alternative sibling (e.g. business_teardown, competitor_landscape) or states an explicit exclusion, so routing against siblings is left to inference.

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?

Discloses the critical, non-obvious trait that this tool 'fetches no data' and that the calling model must run the procedure with its own web search. Annotations cover the read-only/idempotent safety profile, but this execution-model disclosure is something only the description could carry and it is stated plainly.

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?

Front-loads the most important fact (framework, not finished analysis) in the first clause, and the example invocations earn their space. It is somewhat dense and contains a stray double period ('invest..'), but overall the structure is purposeful.

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 framework-returning tool with a 2-param schema, full schema coverage and an output schema, the description covers the tool's nature and execution model thoroughly. The main thing an agent might still wonder is how to distinguish it from adjacent analysis siblings, but the core is 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 100% and both parameters are documented in the schema with examples, so the baseline is 3. The description frames the inputs as 'category x metro' but adds no format or constraint detail beyond what the schema already provides.

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?

States a specific deliverable (a research framework/procedure, output schema and rubric for a category x metro gap analysis) and explicitly distinguishes what it is not ('not the finished analysis'). An agent can tell it apart from siblings like competitor_landscape or pricing_benchmark from the text alone.

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 three example invocations give concrete, unambiguous usage context, and the target audience is stated ('someone deciding whether/where to open, expand, or invest'). It stops short of naming sibling alternatives or explicit when-not-to-use exclusions, so it lands just below the top.

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 safety profile (readOnly, idempotent, non-destructive, openWorld=false), and the description adds substantial context beyond them: the tool fetches no data, holds no prices, returns a procedure/output schema/quality rubric, and the calling model is expected to run the procedure with its own web search. That distinction between 'framework provider' and 'data fetcher' is exactly the behavioral disclosure an agent needs.

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 defining claim is front-loaded ('Returns a research framework, not the finished analysis'), and the examples are a compact, useful block. There is mild redundancy — 'holds no prices itself' and 'fetches no data' restate the same idea, and a stray double period appears — but structure is otherwise tidy.

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 an output schema present and 100% parameter coverage, the return values need no further explanation, and the description nonetheless explains what kind of artifact comes back (procedure, schema, rubric). Annotations cover safety, so nothing an agent needs to call this correctly is missing.

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%, so the schema already documents category, services, and city_metro fully. The examples lightly illustrate category and city_metro in use and the normalization intent touches on services, but the description adds no format or constraint detail beyond the schema. Baseline 3 applies.

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?

States a specific verb and resource (returns a research framework for a defensible local pricing comparison within a category) and explicitly carves out its niche by stating it is 'not the finished analysis' and 'holds no prices itself.' An agent can immediately tell this apart from any data-returning sibling.

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?

Three concrete example invocations give strong cues for when this applies (benchmarking a category in a city, checking market alignment, handling competitors who don't publish prices). However, no explicit alternatives or exclusions are named — it never says 'use X instead' — so it stops short of the top band.

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 goes well beyond the annotations by disclosing that the request goes to a real inbox, is free and requires no account, and must be filed even if the agent lacks all details ('Do not demand any of it: file what you have'). It also mandates verbatim transmission of user request/email, agent-written context, and never claiming success unless status came back 'filed'. These are behavioral rules the annotations cannot capture.

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 longer than average but every section earns its place: purpose, usage triggers, pre-call info gathering, verbatim rules, post-call reporting, and examples. The core purpose is front-loaded in the first sentence, and the examples clarify the intended scenarios without padding. This is appropriate density for a tool with nuanced behavioral requirements.

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 5 parameters, 0 required, and an output schema, the description is essentially complete. It tells the agent when to call it, how to gather and transmit information, what to do with missing fields, and how to report the outcome to the user. It even references the output status ('status came back filed'), which is sufficient because the output schema provides the formal structure.

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 reinforces the verbatim requirement for REQUEST and EMAIL and states 'write context yourself,' but the schema already says essentially the same thing ('VERBATIM — do not summarise', 'This one is yours to write'). The examples illustrate possible values, but they do not add semantically new parameter meaning beyond a high-coverage 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 opens with a specific verb and object: 'Sends a feature request, a data request or a correction straight to the person who builds this server.' It then enumerates the exact fall-short scenarios (question it cannot answer, dataset it does not hold, wrong-looking answer), which clearly separates it from the data-retrieval sibling tools. The name and title are reinforced rather than merely restated.

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 when-to-use conditions: 'Use it whenever this server falls short of what the user actually wanted,' with concrete examples and the instruction that 'Reaching a wall is not the end of the turn; offer to file it.' It does not name alternative tools or explicitly state when not to use it, but the fall-short framing implies the sibling data tools are preferred when they can satisfy the request.

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 discloses the critical non-obvious contract: the tool reads no reviews and fetches no data itself, and the calling model must run the procedure with its own web search to produce the result. This goes well beyond the annotations (readOnly, idempotent, openWorld=false) and is exactly the kind of execution-model disclosure an agent needs, and it is consistent with those hints.

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?

Front-loaded with the single most important fact (framework, not analysis) followed by the no-data-fetch caveat and then examples. The three examples are longer than strictly necessary but earn their place for a routing-heavy, ambiguous-purpose tool; only minor trimming is possible.

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 an output schema present, the description needn't explain return values, and it correctly spends its budget on the execution contract and realistic invocation scenarios. It leaves unstated what happens when a business has no reviews or how to choose between this and overlapping siblings, a modest 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 description coverage is 100%, and each parameter already carries its own explanation (city_metro disambiguates same-named businesses, category sets review-volume expectations). The description adds no parameter-level detail beyond the schema, so the baseline 3 is correct.

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 precise, unusual deliverable: a research framework (procedure, output schema, quality rubric) for mining public reviews, explicitly NOT the finished analysis. It also names the concrete analytical outputs (complaint taxonomy, theme extraction, sentiment trajectory, differentiators, red flags), so an agent knows exactly what it gets back and how it differs from siblings like business_teardown or local_visibility_audit.

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?

Three concrete example invocations establish when to call it (finding real patterns beyond a star rating, checking rating stability over 90 days, buyer-side diligence on staffing/ownership changes). That is clear usage context, but no explicit exclusions or named alternatives among the sibling tools 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?

Adds substantial context beyond the annotations: the catalogue and prices come from the live page, never from memory; a human replies by email; nothing is quoted, charged or scheduled; and the agent must not claim success unless the returned status is 'filed'. The only mild tension is destructiveHint=true versus 'nothing is charged', but that reflects a real external side-effect (a person is dispatched), not a 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?

Front-loaded with the two invocation modes, then constraints, then two concrete example utterances; every sentence carries operational content. It runs long for a four-parameter tool, but the length is justified by the real-world side effects being governed.

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 an open-world, non-idempotent tool with a full schema and an output schema, the description covers what an agent needs: how to discover engagements, what each argument must contain, the human-reply flow, and the status check that gates any success claim. Return-value detail is rightly left to the output schema.

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%, so the baseline is 3, but the description adds meaning the schema does not: `engagement` must be an id taken from this tool's own empty-call listing, `who` determines which records the person pulls, and email/detail must be passed verbatim rather than normalized.

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?

States a specific verb+resource: files an engagement enquiry so a person at Brick & Mortar performs a paid read of the public record. It also distinguishes the two modes of the tool (empty call lists engagements and prices; populated call files the enquiry), so an agent can tell it apart from the free research 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?

Explicit when-to-use ('only after the free tools have been tried or when the person asks for someone to do the work'), a precondition ('confirm with them what will be sent'), and a hard reporting rule (

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 safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is lower. The description adds genuinely useful context beyond them: 'Free, no account,' and that results include real row counts, column names, filtered cuts, and county coverage. It does not, however, mention any rate limits or output size, leaving a small gap.

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?

Front-loaded with the core purpose, then usage routing, then a descriptive list of contents, with example invocations at the end. Every element earns its place, though the example list is somewhat redundant with the already-clear purpose statement.

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?

An output schema exists, so return values needn't be spelled out, yet the description still characterizes the payload (row counts, column names, cuts, counties). Combined with annotations, an agent has everything needed to call correctly; only the lack of output-size or rate-limit guidance keeps it from a 5.

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%, so the single 'about' parameter is already fully documented in the schema. The description does not elaborate on filter syntax or matching behavior beyond what the schema provides, so 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?

States a specific verb (Lists) and resource (public-records datasets) with precise scope (seven-county Minneapolis-St. Paul metro). It clearly distinguishes itself from twin_cities_records by naming it as the follow-up tool, so an agent can route without opening either schema.

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 instructs 'Call this FIRST to learn what can be answered, then call twin_cities_records to ask it,' giving both the ordering and the named alternative. Example invocations reinforce exactly the situations where this tool applies.

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 readOnly, idempotent, openWorld, non-destructive, so the description isn't carrying the safety burden. It still adds real behavioral value: free, no account, nothing stored, and the guarantee that misses come back with a reason rather than a blank. It doesn't discuss rate limits or result size, which keeps it from a 5.

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?

Front-loaded with the core mapping and dense with useful detail; the two example invocations anchor usage cheaply. The middle sentence is long and slightly run-on, but every clause carries information, so it stays efficient.

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?

An output schema exists, so the description need not enumerate return structure, and it correctly focuses on geography, coverage scope, and miss-handling behavior. For a single-parameter lookup with rich annotations, nothing an agent needs is missing.

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?

Only one parameter, and schema coverage is 100% — the schema already explains to include the city because 'Grand Ave' exists in several of them. The description adds no additional syntax or format guidance for the address field, so baseline 3 applies.

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?

States a specific input (one address in the Minneapolis–St. Paul metro) and an enumerated set of outputs (land use, build year, assessed value, last sale, MPCA contamination/storage-tank file, adjoining parcels with owner counts). The scope is narrow and unmistakable, so an agent can distinguish it from a general records tool.

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 says to use it 'the moment an address comes up' and names the follow-on alternative, twin_cities_records, for the surrounding market. Trigger condition and routing are both stated, not inferred.

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 readOnly/openWorld/idempotent/non-destructive, so safety is covered; the description adds genuinely new behaviour: results are capped at six example rows plus a true match count and a link to the full file. It also discloses the radius default and cap via the schema, and the address-omission semantics. Minor gap: no indication of latency or how the 'link' is produced.

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?

Front-loaded with the core capability, then a clean parameter rule, then concrete example invocations that each earn their place by showing the address-present and address-absent modes. The record-type enumeration is long but informative rather than padded.

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 full schema coverage, rich annotations, and an output schema, the description only needs to convey intent and routing; it does that well and even summarises the capped result shape. What remains thin is the relationship to twin_cities_datasets and twin_cities_lookup, which an agent choosing among 15 siblings would want.

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's address guidance ('to answer about one property and its surroundings') largely restates the schema's own wording for `address`, and `scope`, `columns`, and `dataset` are left entirely to the schema. It adds little beyond the structured fields.

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 — 'answers a question about the Minneapolis-St. Paul metro from joined public records' — and enumerates the record types it joins (sales, ownership, adjacency, contamination files, licensing, census). It never names the neighbouring tools (twin_cities_datasets, twin_cities_lookup), so sibling differentiation is left to inference, though the 'joined public records' framing implies it is the query layer over the catalog.

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?

Gives an explicit branch rule: 'Give an `address` to answer about one property and its surroundings; omit it to ask about the whole market cut.' The three example invocations further ground when the tool applies. No exclusions or named alternatives against siblings are given, 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 cover read-only, idempotent, non-destructive and open-world semantics, so the safety profile is handled. The description adds real behavioral value beyond that: results are free with no account required, and the two-call discovery flow (no args to list roles, then role to get a shelf) is spelled out.

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 operational content is front-loaded and each sentence carries the role list, the card taxonomy, or the call pattern. It is somewhat verbose with marketing phrasing ('the front door of brickandmortar.dev') and a slightly redundant example block, but nothing is truly wasted.

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?

Because an output schema exists, return values need not be described, and the description instead fills the real gaps: role enumeration, the card categories, the two-step invocation pattern, and the cost/auth model. An agent has everything needed to call this correctly as a first step.

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%, so the baseline is 3, but the description adds actual semantics: the intended sequencing (call with no arguments first to learn role ids), and the fuzzy-vs-exact distinction implied by 'who' versus 'role'. It clarifies workflow rather than merely restating the 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 states a concrete retrieval verb and resource: it returns the list of supported roles when called with no arguments, or the 'shelf' of cards for a given role. It is clearly the discovery entry point, though it names no sibling tool by name, relying instead on the tagline 'front door' to differentiate itself.

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 explicit routing guidance: 'Call this FIRST when someone says what they do', plus the fallback instruction to ask the user what they do if unspecified. It also states the no-args vs. role argument behavior, so the agent knows exactly which call shape to use at which moment.

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