CREHQ MCP Server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.7
Disambiguation4/5
Each tool targets a distinct resource and operation: locations, companies, datasets, trends, and intelligence. While there are multiple history/event tools (location_history, site_timeline, locations_events, company_changes), their descriptions clarify by scope: single entity vs. site succession vs. cross-brand stream vs. brand-scoped changes. Some overlap exists but overall the boundaries are clear.
Naming Consistency3/5
The dominant pattern is 'crehq_<resource>_<action>' (e.g., locations_list, company_get), but there are notable deviations like crehq_request_upgrade, crehq_whitespace, crehq_co_tenancy, and crehq_intelligence_preview. Also inconsistent singular/plural usage (location_get vs locations_list, company_get vs companies_list). The naming is readable but not fully uniform.
Tool Count2/5
33 tools is a large surface for an MCP server. While each tool has a distinct function, the sheer number may overwhelm agents and increase selection effort. Some tools could be consolidated (e.g., dataset list/categories/download, or merging company_changes with locations_events).
Completeness4/5
The domain is well-covered for a read-only commercial real estate data platform: location lookup and search, brand and franchise intelligence, historical timelines and site succession, point-in-time occupancy, datasets, trends, and premium analyses like whitespace and co-tenancy. No obvious dead ends; only minor gaps like write operations (not expected) or direct location-to-company-contact cross-references.
Average 4.1/5 across 33 of 33 tools scored. Lowest: 3.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 11 commits in the last 12 weeks
- Last stable release on June 17, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions the underlying data source and tier restrictions, but does not disclose behavior such as what happens when no whitespace exists, potential response format, or access limitations. Phrases like 'PREMIUM INTELLIGENCE' are promotional and do not add behavioral clarity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and gets to the point quickly, but contains marketing fluff and an unnecessary 'PREMIUM INTELLIGENCE' lead-in. Despite minor excess, it remains reasonably concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, so the description must clarify return values. It states a 'ranked, data-driven shortlist' but does not specify what fields are included, how results are structured, or how to interpret the output. It also does not elaborate on the 'country' parameter's role beyond the schema default.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both parameters with 100% coverage, so the baseline is 3. The description adds no parameter-specific detail beyond what the schema provides; it simply frames the overall purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function: it performs whitespace analysis to find postal codes/markets where competitors are present but the brand is absent. It uses specific terminology like 'ranked, data-driven shortlist' and distinguishes itself from sibling tools by focusing on expansion opportunities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for expansion planning ('where a chain should expand next') but does not explicitly state when to prefer this tool over siblings or provide conditions for non-use. No alternative tools are mentioned, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that traffic counts are only present 'when backfilled' and that event rows distinguish verified openings from other events. However, it does not describe other behavioral traits such as read-only nature, sorting order, or response structure beyond the content list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and key content categories, and includes a concrete example. It is concise without being overly terse, though a direct verb at the start would be slightly more effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and lack of output schema, the description covers the main content areas (event timing, traffic, demographics, etc.), provides a usage example, and clarifies event row semantics. The schema supplies parameter defaults, so the description is sufficiently complete for selection and basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does not add parameter-level details beyond the schema (e.g., defaults for limit, event_type, or the meaning of only_with_traffic), so it neither improves nor detracts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides 'context for a brand's most recently observed locations' and lists the types of context included. It differentiates from sibling tools by focusing on recency and providing a concrete example question, though it lacks an explicit action verb like 'retrieve' or 'get'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes a helpful example question ('traffic counts for the last 50 Starbucks locations CREHQ observed') that implies appropriate use cases, but does not explicitly state when to use this tool over alternatives like crehq_location_history or crehq_locations_list, nor does it mention any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It does disclose the return contents (outlet counts, fees/royalties, financial trajectory) and the single-brand scope. However, it omits any operational details such as data freshness, whether prior purchase is required, or how time ranges are determined, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and front-loaded with concrete deliverables. The second sentence, 'The growth/health curve of a concept in a single call,' is somewhat interpretive but not redundant; it adds a useful mental model. No wasted words, though it could be more action-oriented.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should help the agent anticipate return data. It lists three concrete components (outlet-count history, fee/royalty trends, FDD financial trajectory) and the time-series nature, which is sufficient for a simple one-parameter tool. It does not detail formatting or date ranges, but the provided context is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single 'id' parameter (described as 'CREHQ company id'). The description reinforces that the tool targets 'ONE brand,' which maps to the id, but adds no additional semantic nuance beyond the schema. Baseline 3 applies since the schema fully documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource: time-series trends for a single brand, and lists the specific data components (outlet-count history, fee/royalty trends, FDD financial trajectory). It distinguishes from likely siblings by emphasizing 'ONE brand' and a comprehensive 'growth/health curve' in a single call, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'The growth/health curve of a concept in a single call' implies when to use this tool (when a consolidated trend overview for one brand is needed), but it does not provide explicit exclusions or name alternative tools like crehq_trends_geographic. Usage context is present but not sharply defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the read-only nature ('List'), the response contents (links to store counts, FDD financials, real-estate criteria, contacts), and pagination. However, it omits details like auth requirements, rate limits, default ordering, or behavior when no results match.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and front-loaded with the core action. Each sentence adds distinct value: scope, filters, record contents, and pagination. No filler or redundant repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with optional filters and pagination, the description covers the essential aspects: what is returned (companies), what each record links to, and pagination. It works well even without an output schema or annotations, though a bit more on response structure or default behavior would make it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage of all four parameters, so the baseline is 3. The description adds marginal context (e.g., 'discover brands actively opening or closing units' relates to expansion_status) but largely repeats what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('franchise & multi-unit brands tracked in CREHQ's ... database'), enumerates verticals, and clarifies the filtering capabilities. It clearly implies a list/explore tool distinct from search/get siblings, though it does not explicitly name alternatives like `crehq_companies_search`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear use case ('Filter by category or expansion status to discover brands actively opening or closing units') but does not explicitly state when to use this tool versus `crehq_companies_search` or `crehq_company_get`, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It usefully discloses that the data is 'CREHQ-modeled from observed location/context data' and explicitly states it is not a brand-stated requirement sheet, which is a key behavioral trait. However, it does not mention any operational aspects such as read-only nature, response format, or error handling, leaving some transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and then a clarifying caveat. Every phrase contributes information—no filler or repetition. It is efficiently structured and easy to skim.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input schema (one parameter) and no output schema, the description provides a substantial list of return value categories (traffic/AADT, route class, demographics, etc.), which offers a good sense of what the tool returns. It is incomplete only in not describing the exact structure of the output, but for a profile retrieval tool it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single parameter entity_id, which is described as 'CREHQ location entity_id.' The description adds no additional meaning beyond the schema, so the baseline of 3 applies; it does not compensate with extra context about the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource ('CREHQ Modeled Site Profile for one physical location') and the scope ('one physical location'), listing the types of data included. However, it lacks an explicit verb like 'retrieves' or 'gets', making the action implicit. It does distinguish itself from siblings by emphasizing 'modeled' data and the 'not a brand-stated requirement sheet' caveat, which differentiates it from other site-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining a modeled profile of a specific location, but does not explicitly state when to use it versus alternatives like crehq_location_get or crehq_site_timeline. There are no exclusions or alternative tool mentions, so usage guidance is only implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the transparency burden. It adds provenance ('Sourced and multi-source-verified from state franchise registries') and a caveat ('where disclosed'). However, it doesn't disclose behavior when no franchise data exists, potential errors, or response format, leaving gaps in behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
At two sentences, the description is efficient and front-loaded with the action. The second sentence adds contextual value through sourcing and audience, though 'the hard numbers...' is slightly promotional. Overall, every sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter schema and no output schema, the description adequately lists the returned data categories and their sourcing. It doesn't describe exact response structure, but the listed items give a good mental model for a franchise financials lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single 'id' parameter, including its source ('from crehq_companies_search'). The description adds no additional parameter-level details, so it meets the baseline but doesn't exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Retrieve'), names the exact resource ('FDD-derived financials for a brand'), and enumerates key data fields (franchise fees, royalty rates, total initial investment ranges, Item 19). This clearly distinguishes it from sibling tools like crehq_company_real_estate or crehq_company_credit_signals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
While it doesn't explicitly name alternative tools, the description establishes clear use context: 'an analyst, investor, or prospective franchisee needs to underwrite a concept.' It also notes 'where disclosed,' signaling when data may be absent. No explicit exclusions are given, but the context is strong enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the tool returns a next-since cursor for incremental polling and lists the event categories. However, it does not mention pagination specifics, rate limits, or potential edge cases (e.g., how the stream handles deletions), which would be valuable given the absence of structured annotation metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences and reasonably compact. The first sentence defines the core action, the second provides context/value, and the third explains the cursor. The second sentence is mildly promotional but still informative; overall, it earns its place without excessive verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 output schema), the description is nearly complete. It explains the event stream, the cursor for incremental polling, and the intended use cases. It does not describe the exact shape of returned events, but with no output schema and a stream of known event types, it provides enough for an agent to invoke and interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 both 'since' and 'per_page'. The description reinforces the timestamp usage and cursor-based polling, but adds no new parameter details beyond what the schema provides. Thus, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Pull') and resource ('cross-brand location LIFECYCLE STREAM'), and enumerates the event types (openings, closings, relocations, ownership/brand changes). This clearly distinguishes it from sibling tools like locations_list (current state) and location_history (single-location history).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit use cases ('drives prospecting, market-monitoring, and who's moving right now alerts') and implies it is for real-time change tracking. It does not explicitly name alternative tools or exclusions, but the context is clear enough for an agent to choose this over a list or search tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the full burden of behavioral disclosure. It does convey the read-only feed nature, time-bounded scope, and optional event-type filtering, but it omits details like ordering, pagination, default return shape, and any authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core functionality and scope. The second sentence efficiently adds position relative to the lifecycle stream and the intended use case. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, the description does a solid job of explaining what the tool does, its brand scope, time bounds, and optional filter. It could enhance completeness by mentioning ordering or default limit behavior, but it 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for all 5 parameters (100% coverage), so the baseline is 3. The description adds only a high-level connection to the feed's purpose (time bounds, event-type filter) without introducing new semantic details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a 'date-bounded feed of everything that changed for ONE brand's footprint' with explicit event types (openings, closings, relocations, attribute edits). It also distinguishes this tool as 'the brand-scoped version of the lifecycle stream,' clearly separating it from sibling tools that may be location-scoped or global.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a clear use case ('ideal for monitoring a target account') and implies this is the brand-level variant of a broader lifecycle stream, giving an agent context for when to choose it. However, it does not explicitly name alternative tools or state when not to use it, stopping short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full transparency burden. It does add useful context about data provenance ('compiled from public records and the brand's own disclosures'), but it does not disclose potential limitations such as data freshness, pagination, or whether the information is gated by purchases/dataset access. For a read-only lookup this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action and resource. The second sentence is a concise, memorable use-case metaphor rather than fluff. Every word adds value, and there is no repetition of schema or annotation details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no output schema, the description provides the needed context: what contacts are included, the data source, and when to use it. It does not explain return format or possible empty results, but the simplicity of the tool and the schema make this sufficient. A score of 5 would require more detail on output shape or edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' already has a schema description with 100% coverage, explicitly stating it comes from crehq_companies_search. The tool description adds nothing about the parameter format or how to resolve it, so it relies entirely on the schema. This meets the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Get') and resource ('real-estate decision-maker contacts for a brand'), then lists concrete role types (development, site-selection, franchising). This clearly distinguishes it from sibling tools like crehq_company_get or crehq_company_real_estate, which focus on other aspects of company data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'The shortcut from which brand is expanding to who do I email' gives a clear scenario for when to use this tool. It implies the tool is for prospecting/outreach, but it does not explicitly state when not to use it or mention alternatives, so it falls short of full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 point-in-time nature and historical footprint but omits details like potential prerequisites, data accuracy, or explicit mention that it is read-only. It adds value but is not fully transparent about limitations or edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: a bolded core statement, a clarifying Q&A, and a use-case framing. Every sentence earns its place, and the most important information is front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and full schema coverage, the description adequately explains the query's purpose and expected conceptual output ('how many units... and where') but does not specify the exact return structure. Since there is no output schema, a bit more detail could be added, but the current level is sufficient for most agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 tool description reinforces the meaning of the 'date' parameter (point-in-time snapshot) but adds no new details for 'id', 'limit', or 'offset'. It does not compensate beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('reconstruct'), resource ('which locations a brand operated'), and temporal scope ('given historical date'). It distinguishes itself from siblings by emphasizing 'POINT-IN-TIME' and contrasting with 'today's count', making its unique purpose immediately apparent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies when to use the tool ('given historical date', 'growth-curve and same-store analysis') and explicitly says it is 'not just today's count', which implies when not to use it. However, it does not name a specific sibling tool as an alternative, so it falls 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the premium tier restriction and implies the output is a ranked list of co-locating brands, but lacks details on pagination, result limits, data freshness, or rate limits. This is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured. Each sentence earns its place: the premium qualifier, the core explanation with an example, and the practical use cases. No redundant or unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple schema and the absence of an output schema, the description covers the core purpose and use cases well. It conveys the output as co-locating brands, though it doesn't specify result limits or ranking details, which are minor omissions for tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides complete descriptions for both parameters (company_id and radius_meters), so the tool description adds no extra parameter semantics. Schema coverage is 100%, justifying the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool's purpose: co-tenancy analysis identifying which brands co-locate near a given brand's stores. The example using Chipotle clarifies the concept, and the description distinguishes this tool from siblings by focusing on cross-brand clustering patterns rather than individual locations or contacts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases (site-selection, anchor-tenant matching, trade-area benchmarking) which imply when to use this tool. However, it does not explicitly name alternative tools or state when not to use it, so it falls 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. 'Browse' implies a read-only operation, and it mentions what entries expose (row counts, schema, refresh date), but it omits pagination behavior, authentication requirements, or rate limits. This is a clear but incomplete behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the tool's purpose, and contains no fluff. Every phrase adds value, including the examples and output fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a browse/list tool with optional filters and no output schema, the description explains what the data looks like (row counts, schema, refresh date) and the available filters. It is sufficient for an agent to understand the tool's role, though it could mention pagination (per_page) to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 mentions category, country, and freshness filters, which adds a contextual summary, but it does not add syntax or semantics beyond the schema. The per_page parameter is not mentioned in the description, so it adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool browses CREHQ's catalog of packaged datasets, with examples (whole-brand footprints, vertical rollups, FDD financials) and explicitly calls it 'the menu of bulk data products', distinguishing it from sibling tools like crehq_purchased_datasets_list and crehq_locations_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for discovering available datasets before licensing, and the phrase 'menu of bulk data products' contrasts with purchase/download tools. However, it does not explicitly mention alternatives or exclusions, so it falls 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.
Behavior3/5
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 that the tool provides an append-only event log with dates and sources for one location, implying a read-only historical operation. However, it does not mention the limit parameter behavior (default 200, max 1000) or any potential side effects/access restrictions, leaving some behavioral traits undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, front-loading the core purpose and then elaborating on the event types and provenance. Every word adds value, with no tautology or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must explain return values. It does so by enumerating event types (open/close/rebrand/attribute change) and noting 'dates and sources'. For a two-parameter log tool, this is sufficient, though it could be slightly more complete by mentioning response limits or ordering.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents both parameters (entity_uid and limit) with descriptions, so the baseline is 3. The description adds emphasis that entity_uid identifies a single physical location, but it does not add new semantics or format details beyond the schema, so the baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a 'Full append-only event log for ONE physical store/site (by entity_uid)', specifying both the resource and scope. It distinguishes from sibling tools like crehq_locations_list or crehq_location_get by emphasizing the singular location and historical nature, meeting the 'specific verb+resource' + sibling differentiation bar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly sets the usage context: this tool is for retrieving the complete historical record of a single physical location, as evidenced by 'ONE physical store/site' and the event types listed. It does not explicitly name alternatives or exclusions, but the scope and append-only nature make its purpose distinct, placing it between 'implied' and 'clear context without exclusions'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It conveys that this is a read-only bulk fetch, but it does not mention pagination behavior, the requirement to supply at least one filter (since the schema has no required parameters), or the response format. This is a moderate gap given the lack of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose ('Bulk location retrieval'), and wastes no words. It efficiently covers what, how, and when without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params, no output schema, no annotations) and the large sibling set, the description does a solid job of explaining the use case and differentiation. However, it leaves out that no parameters are required (schema shows required: []), which could confuse an agent about whether a call with zero filters is valid, and it does not mention pagination despite the per_page parameter. These omissions are partially mitigated by the schema but still represent incompleteness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all parameters, so the baseline is 3. The description reinforces the three filter modes and adds an example for 'polygon' (custom market boundary), but it does not add significant semantics beyond the schema, such as how parameters interact or constraints on combination.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's primary function: bulk location retrieval for ETL/pipeline use. It specifies multiple input methods (ids, brands, GeoJSON polygon) and explicitly distinguishes itself from single-location tools by advising against looping, making it easy for an agent to select this over siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: ETL/pipeline, hydrating a dataset, and when not to use it (looping single-location calls). It does not name the alternative sibling tool directly, but the guidance is clear enough that an agent would infer crehq_location_get is the single-location alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that results are distance-sorted and government-verified, which adds behavioral context. However, it does not specify authentication requirements, rate limits, or potential side effects (though likely read-only). This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the core purpose ('Radius search'), and every sentence adds value. It fits in two sentences with no redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with a fully documented schema, covers the tool's functionality well. It explains the return format (distance-sorted, government-verified storefronts) and mentions coverage across verticals. While there is no output schema, the description provides sufficient context for an agent to invoke the tool correctly. Slightly less complete than the TDQS 4.3 reference due to more parameters, but still strong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented in the schema. The description adds use-case context but does not provide additional semantics for individual parameters beyond what the schema offers. This aligns with the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function as a radius search for locations near a lat/lng point. It uses a specific verb ('find') and resource ('tracked locations') within a defined scope (radius in miles), and it is distinguishable from sibling tools like locations_search and locations_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists use cases ('trade-area analysis, competitor mapping, and what's near this address questions'), providing clear context for when to use the tool. It does not explicitly name alternatives or give exclusions, but the use cases are sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the burden of behavioral disclosure. It states the tool performs a multi-field search, which implies a read-only operation. However, it does not elaborate on any behavioral traits such as result ordering, fuzzy matching behavior, pagination limits, or whether all fields are optional. This is adequate for a straightforward search tool but lacks richness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two sentences, is front-loaded with the primary action, and contains zero wasted words. Every phrase adds information: the search fields, the fuzzy use case, and the contrast with ID lookup.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no output schema, the description covers the core use case and parameter semantics (via schema). It does not mention return values or response format, but that is often implied for search endpoints. It also fails to differentiate from other location search variants like `crehq_locations_nearby`, but given the explicit field list, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 restates the parameter names in narrative form ('name, brand, street address, city/state/geography') but adds no additional semantics beyond what the schema already provides. It does not mention that all fields are optional or how they combine, which would add value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Search'), resource ('locations'), and scope ('across multiple fields at once'). It enumerates the fields (name, brand, street address, city/state/geography) and explicitly distinguishes from ID-based lookup with 'rather than an id.' This differentiates it from sibling tools like `crehq_location_get`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Use when you have a fuzzy description of a physical place rather than an id.' This supplies a clear use case and an exclusion (not for exact ID lookups). It does not name alternative tools explicitly, but the 'rather than an id' implies `crehq_location_get`, and the multi-field search is clearly distinct from simpler list or nearby tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains that the tool returns every brand that ever occupied the address and the timing, which conveys the core behavioral contract. It omits output format details but remains sufficiently transparent for a read-only query tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core function is front-loaded, but the descriptive quality suffers from marketing language ('FLAGSHIP DIFFERENTIATOR', 'Unmatched', 'No other location dataset...') that adds emphasis rather than instruction. The example is useful, but the hype could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives enough context for a single-parameter tool: what it returns, the temporal range, and example use cases. Since there is no output schema, the description adequately conveys the return semantics, though it does not specify empty-result behavior or ordering details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameter is already well documented. The description only restates that site_uid identifies the physical site, adding no new semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('return') and resource ('full chronological tenancy history') for a given physical site. It clearly differentiates from siblings by emphasizing address-level succession, explicitly noting no other location dataset reconstructs this.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use cases ('backfill/teardown analysis, second-generation space, and landlord due diligence'), which signal when to invoke the tool. It does not explicitly name alternatives or state when not to use it, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that the tool surfaces market trends and covers metro/state concentration, adding useful context. However, it doesn't explain data aggregation, recency, or any limitations, leaving some behavioral aspects unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with front-loaded purpose. Every phrase adds value: introduces the analysis type, mentions the geographic scope, and clarifies the output (heating/cooling markets). No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an analytics tool with optional filters and no output schema, the description is fairly complete. It covers what the tool does and what it reveals. It lacks details on output structure or data limitations, but these are less critical given the simple parameter set and read-only nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds contextual meaning by linking 'metro/state' to the state parameter and 'verticals' to category, but doesn't provide additional syntax or format details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs geographic trend analysis, specifically metro/state concentration and opening/closing velocity. It also says it surfaces heating/cooling markets, which distinguishes it from sibling trends_company and other location-specific tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use it (when interested in geographic patterns across brands and verticals) and implicitly differentiates from crehq_trends_company by focusing on geographic footprint. However, it doesn't explicitly state when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the output is empirical/modeled rather than authoritative, and adds the caveat about not presenting as stated requirements. This is a key behavioral trait. It does not discuss auth, rate limits, or read-only status, but the modeled-vs-stated distinction is substantive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first packs the content scope, and the second adds usage and caveat. Both are necessary; no filler. The first sentence is long but informative, and the caveat earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description partially substitutes by listing what the response includes (medians, ranges, percentiles, mix types, layer coverage/confidence). It also explains the nature of the data. It lacks some details like response envelope or pagination, but the essentials are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all 4 parameters, so the baseline is 3. The description does not add any parameter-level meaning beyond what the schema already provides, but it also doesn't need to since the schema fully documents each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a 'CREHQ Modeled Site Pattern' for a brand, with a specific verb phrase 'Use this to infer revealed-preference site patterns'. It lists distinct output metrics (empirical medians, road-type mix, co-tenant mix, trade-area density, etc.) that differentiate it from sibling tools like raw location lists or company real estate data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states explicitly to use the tool for inferring revealed-preference site patterns, and warns against presenting results as company-stated requirements without provenance. This provides clear when-to-use and when-not-to-use guidance, though it does not name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It transparently lists the metadata fields returned (row count, column schema, coverage, etc.), but it does not disclose potential error behavior (e.g., invalid slug), or explicitly state that no data values are returned. The read-only nature is implied by 'Get' but not stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the core action first, then specifies the metadata contents in a dash-separated list. Every word earns its place; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema or annotations, the description is complete: it explains what the tool returns (detailed metadata fields) and its purpose (evaluation before download). No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single parameter 'slug', including the guidance that it comes from crehq_datasets_list. The description only repeats 'by slug' and adds no extra semantic detail beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('full metadata for one dataset by slug'), clearly distinguishing it from sibling tools like crehq_datasets_list (listing) and crehq_dataset_download (downloading). It also enumerates the metadata contents, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'everything needed to evaluate it before download' provides clear context that this tool is for pre-download evaluation, differentiating it from download/list tools. However, it does not explicitly name alternative tools or state when not to use it, falling short of the highest bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by enumerating the specific data returned (location count, vertical, ownership, etc.). It adds caveats like 'where known' for private-equity backing, signaling potential data limitations, though it doesn't address error or access scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the core function and payload, the second reinforces its authoritative nature. Every word earns its place, and the most critical action word 'Get' appears first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter get operation with no output schema, the description lists the key return elements to set expectations. It could mention not-found behavior or access restrictions, but given the tool's simplicity and the richness of the data list, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the single 'id' parameter with its origin. The description adds no new parameter-level detail beyond the schema, and with 100% schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get a single brand's canonical CREHQ profile,' providing a specific verb, resource, and scope. It distinguishes from siblings like crehq_companies_search and crehq_companies_list by emphasizing 'single,' 'canonical,' and 'authoritative, de-duplicated source-of-truth.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this tool is for retrieving a single brand's authoritative profile when the ID is known, especially contrasting with search/list tools. However, it does not explicitly name alternative tools or state exclusions, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the response fields (snapshot_as_of, hosted_access_until, artifact basis, row results) and the expiration behavior (returns an upgrade/update-plan message while acknowledging ownership). This goes beyond basic read/write hints, though it does not describe pagination or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core purpose, then scope, then behavior. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 optional parameters and no output schema, the description provides essential context: ownership, snapshot nature, expiration behavior, and high-level response contents. It does not explicitly state whether a dataset or purchase_id is required, but the schema descriptions for those params implicitly cover it. Overall sufficient for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add parameter-specific semantics beyond what the schema already provides. It only contextualizes the purchase relationship, not how parameters combine or interact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (Query rows) and a specific resource (purchased dataset snapshot). It distinguishes this from live CREHQ refresh, and lists response fields, 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states this is for buyer-owned point-in-time snapshots, not live CREHQ refresh, implying when to use it. It also references the prerequisite purchase_id from a sibling tool. However, it does not name specific alternative tools for live data or provide explicit 'when not to use' scenarios beyond the live refresh contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses the requirement for 'credit-intel access' and the behavior when unavailable/scope-gated, which is helpful. However, it does not explicitly state read-only semantics or potential side effects, though the tool name implies a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose and a clear label, followed by a detailed but relevant list of data types. It is longer than minimal but every sentence contributes to usage or content expectations, with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich set of data returned (credit signals, ratings, capital structure, events), the description provides a comprehensive overview of outputs and use cases. It lacks explicit mention of output format or limits, but the absence of an output schema is compensated by the detailed enumeration of content.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single parameter, with a clear description referencing crehq_companies_search. The tool description adds no additional parameter detail beyond identifying it as a company id, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets CREHQ Credit Signals for a brand, enumerating specific data types (ownership, PE sponsor, rating history, capital structure, etc.). This specific verb+resource+content distinguishes it from siblings like crehq_company_get or crehq_company_franchise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use guidance is given: 'Use this when the user asks about tenant credit, creditworthiness, lender diligence, leverage, ratings, sponsor ownership, or distress/health signals.' It also provides an explicit alternative via crehq_request_upgrade if access is unavailable, making the guidance actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the licensing prerequisite ('Requires a tier/contract that includes the dataset') and the return behavior ('raw payload (or a signed link)'). This covers the primary behavioral traits, though it doesn't address error cases or rate limits – acceptable for a simple download tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the action and resource. Every sentence adds value: what the tool does, the formats, the requirement, and the return type. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only 2 parameters, no output schema, and no annotations, the description is complete: it identifies the required input (slug), the optional format with enum, the licensing prerequisite, and the return payload behavior. It sufficiently supports direct ingestion use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100% (both slug and format are described). The description mentions 'by slug' and lists format values, but this largely restates the schema. No significant new parameter semantics are added, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Download a licensed dataset by slug' – a specific verb and resource – and lists the supported formats (CSV, JSON, GeoJSON, XLSX). This clearly distinguishes it from sibling tools like crehq_dataset_get (likely metadata retrieval) and crehq_datasets_list (listing datasets).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 the tool: you need a licensed dataset and want to download it in a specific format, and it notes the prerequisite of a tier/contract. However, it does not explicitly mention alternative tools for non-download operations, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full transparency burden. It discloses the return payload in detail, including attributes and verification sources, which goes beyond the schema's minimal parameter info. It does not mention error handling or authorization, but for a simple single-record lookup, the output disclosure is substantive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that leads with the core purpose and then provides concrete examples of the returned fields. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter get-by-id tool with no output schema, the description adequately maps the expected return values (address, brand, status, attributes, sources). It does not cover edge cases, but these are less critical given the tool's narrow scope, and the return-value detail compensates for the missing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the sole parameter 'id' with a clear description ('CREHQ location id'), giving 100% schema coverage. The description's 'by id' simply restates the schema and adds no extra format, type, or usage detail, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Gets one location's full record by id' and enumerates the specific content (geocoded address, brand, lifecycle status, attributes, sources). This specific verb+resource combination distinguishes it from siblings like crehq_locations_list, crehq_locations_search, and crehq_locations_nearby.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool's usage context is clear: use when you have a specific location id and need the full record. However, it does not explicitly point to alternatives (e.g., crehq_locations_bulk for multiple records or crehq_locations_search for queries), so it lacks explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the output composition (entity_uid, geocoded address, open/closed status, multi-source verification trace), explicitly lists excluded data categories, and mentions the 'bounded' behavior for free sandbox keys. This provides substantial behavioral transparency beyond structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with the first sentence stating purpose. The remaining sentences add needed exclusions and usage context, though the final sentence is somewhat long. Each sentence contributes value, but the overall length could be trimmed slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description compensates by listing key output fields and exclusions. It also gives usage guidance for sandbox keys. However, given the large sibling tool set, it does not explicitly differentiate from other location-listing tools (search, nearby, get), making contextual completeness slightly less than optimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 context by mentioning filters (brand, state, category) but does not add meaningful semantics beyond what the schema already documents. It does not describe pagination, provenance behavior, or parameter formats in more detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists individual store/branch/site records with explicit filters (brand, state, category), and distinguishes its output from premium tools by listing what it excludes. This provides a specific verb+resource+scope that is immediately comprehensible.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes a use case ('Free sandbox keys can use this as a bounded brand lookup') and provides alternatives for excluded data ('use the relevant premium tool... otherwise call crehq_request_upgrade'). However, it does not contrast with sibling listing/search tools like crehq_locations_search or crehq_locations_nearby, leaving some usage ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It goes beyond a simple purpose statement by detailing the exact returned fields: 'snapshot_as_of, hosted_access_until, whether hosted MCP querying is active, and whether the buyer still owns the file snapshot after hosted access expires.' This gives agents concrete expectations about the tool's output and decision-relevant nuances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and every sentence adds value. The first sentence states what the tool does; the second sentence lists the key returned fields. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description is complete: it states the purpose, when to use it, and what the returned data includes. It also explains a subtle concept (owned-file vs hosted-MCP access) that helps the agent understand the tool's relevance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for its single parameter, include_expired, including a description that explains the default and its rationale. The tool description itself does not elaborate on the parameter, but since the schema already fully documents it, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'List dataset snapshots purchased by the owner of the connected CREHQ self-serve key.' This clearly distinguishes it from sibling tools like crehq_datasets_list, which is a general dataset list, while this is specifically for purchased snapshots.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 this before querying a buyer-owned dataset through MCP.' It provides clear context for the intended workflow, though it does not name alternative tools or explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool returns categories with counts and presents itself as a 'quick map', indicating a lightweight read-only operation. It does not mention potential limitations like pagination, but for this simple listing tool it is adequately transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the primary action ('List all dataset categories with counts'), and contains no redundant or filler text. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description provides a clear indication of what is returned (categories with counts) and context (organization across verticals). It could be more explicit about what counts represent, but overall it is sufficiently complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is effectively 100% and the baseline is 4. The description adds value by framing the output as a 'quick map' with counts, which clarifies the nature of the returned data beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb "List" and resource "dataset categories" with counts, clearly distinguishing from sibling tools like crehq_datasets_list which list datasets themselves. The added context of a 'quick map' of organization across verticals further clarifies purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing a high-level overview of dataset categories rather than specific datasets or locations, but does not explicitly name alternatives or when-not-to-use scenarios. The 'quick map' phrasing gives clear context without formal exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains that the tool handles messy/alias names (e.g., 'mcdonald-s' → McDonald's Corporation) and performs full-text search with canonical ID resolution. This provides meaningful context beyond the schema, though it stops short of describing return format or edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and includes a helpful example and explicit workflow instruction. Every sentence earns its place with no unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While purpose and usage are excellently covered, the description does not explain the response structure, how to handle multiple matches, or behavior when no match is found. Since there is no output schema, this gap leaves the agent uncertain about result interpretation. The strong workflow context partially compensates, but completeness is not fully achieved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that 'q' is a brand/company name, gives an alias example, and ties the parameter to the canonical-ID resolution purpose. This goes beyond the schema's basic 'Search term' description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'Full-text search CREHQ's brand universe by name to resolve a company to its canonical CREHQ id.' It clearly distinguishes itself from siblings like crehq_companies_list by emphasizing the resolution to a canonical ID and providing a concrete alias example.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'ALWAYS use this first to get a company_id before calling company detail, credit signals, franchise/FDD, real-estate, contacts, occupancy, whitespace, or co-tenancy tools.' This names specific alternative tools and clearly defines the prerequisite workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses key behavioral traits: the data is 'PREMIUM' and may be 'unavailable or scope-gated', which alerts the agent to access restrictions and a fallback behavior. It implies a read-only operation ('get') but does not detail rate limits, error handling, or response formats. Adding the premium/gated context goes beyond minimal disclosure, hence a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and every phrase is purposeful. It leads with a bold label (PREMIUM SITE-SELECTION DATA), then defines the resource and data fields, followed by target users and a fallback action. No filler or redundancy; it is optimally compact and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter lookup tool with no output schema, the description provides sufficient context: it lists the returned data categories, identifies the target audience, and includes a fallback option. It covers the essential usage and content well, and does not need to describe return formats beyond what is already implied by the data list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage: one parameter 'id' with a description ('CREHQ company id from crehq_companies_search'). The tool description adds no additional semantics about the parameter, so the baseline of 3 applies given high schema coverage. No extra value beyond the schema is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function: retrieving a brand's site-selection criteria and target real-estate profile. It enumerates specific data elements (preferred site types, building/lot size, geographies, expansion markets) and uses an explicit verb ('get') with a specific resource. It also implicitly distinguishes from sibling tools like crehq_company_get by focusing on real-estate criteria.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states exactly when to use the tool: for landlords, brokers, and site-selectors who need to know a tenant's requirements before pitching. It also provides a clear alternative: if data is unavailable or scope-gated, use crehq_request_upgrade with requested_data='site_selection_criteria', offering an explicit fallback and preventing a wrong response.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral burden. It discloses that the tool returns an upgrade prompt and records the requested topic as a paywall/upgrade-intent signal for follow-up. It also warns against misleading the user about data availability, which is valuable behavioral guidance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but well-structured: a clear 'Use this when' opener, a detailed list of covered data types, the return behavior, and a 'Do NOT' caution. The extensive list is necessary to convey scope. Slightly verbose but every part serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers purpose, usage, and side effects sufficiently. It could mention the exact return format or behavior for non-free keys, but the core execution context is clear. The tool is simple enough that this description is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all parameters (100% coverage), so baseline is 3. The description adds value by elaborating the enum categories (e.g., 'ownership/sponsor/capital-structure/rating-history data' clarifies 'credit_profile'), helping the agent choose the correct requested_data value. It also provides an example for the brand parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: handle requests for data not in the free sandbox by returning an upgrade prompt. It explicitly lists the covered data categories, distinguishing this from sibling tools that retrieve specific data types. The verb 'Use this when' and the described outcome 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use guidance (when user asks for paywalled data) and a strong when-not directive (do not tell the user the data doesn't exist). It does not explicitly name alternative sibling tools, but the context implies those exist for included data. This is strong but lacks explicit alternative naming for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses credit consumption (one monthly credit), the bounded nature of returns, and exclusions (no raw premium tables, no redistribution rights). Also explains the free-key behavior with a 402 prompt. This exceeds what annotations would provide, and no annotations are present to contradict.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action, and each sentence adds valuable context: credit consumption, return type, exclusions, and upgrade prompts for different key types. No filler or repetition; compact for the amount of guidance provided.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description explains the return type ('bounded evidence frame') and its limitations, which is adequate for a preview tool. It also covers pricing/access contexts and alternatives. Minor gap: the exact structure of the evidence frame is not described, but for a controlled preview this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with descriptions for all three parameters, so the baseline is 3. The description does not add significant parameter-specific semantics beyond what the schema already states, though it does enumerate question types that roughly map to preview_type enum values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a bounded evidence frame for specified question types (tenant-credit, site-selection, etc.), distinct from other CREHQ tools. It uses specific verbs and resources, and differentiates itself as a credit-based preview rather than a raw premium data access tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: for CREHQ Pro self-serve keys with a monthly preview credit, and when not: free keys get a 402 upgrade prompt, and full enterprise keys should use dedicated premium tools directly. Names the alternative category of tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It fully lists the return fields (affiliation_status, canonical name, entity type, brand, operator, parent company, confidence, evidence, checked time) and explicitly states that independent, not_a_commercial_venue, and unresolved are valid outcomes, warning against inventing affiliations beyond the evidence. It also discloses a payment flow (purchase_url, intent_id, Pro key installation) and the need to reconnect, which is an important behavioral side effect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized for the tool's complexity. It is front-loaded with purpose and usage, then details parameters, return values, and special cases. Each sentence provides distinct information—no fluff—and the structure flows logically from what to when, how, and edge behaviors.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and no annotations, the description is exceptionally complete. It covers the tool's purpose, appropriate usage, input criteria, full list of return fields, acceptable outcome statuses, and a specific paid-access workflow. This equips an agent to select and invoke the tool correctly, even without additional structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all 5 parameters (100% coverage), so the baseline is 3. The description adds meaningful semantic value by specifying that at least one of url, venue_name, or address is required (though the schema allows empty) and that additional identity hints improve disambiguation. This is crucial guidance not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: resolving a public venue or business identity into its affiliation (chain, brand, operator, owner, or independent). It defines specific use cases (asking which chain a venue belongs to, who operates it, or if it's independent) and lists categories (hotels, restaurants, etc.), making it easy to distinguish from sibling tools like crehq_locations_search or crehq_company_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this when the user asks which chain or brand a venue belongs to, who operates or owns a location, or whether a venue is independent,' providing clear when-to-use context. It also instructs to provide at least one of url, venue_name, or address and notes that additional hints improve disambiguation. However, it does not explicitly mention when not to use the tool or name alternative tools for other cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![crehq-mcp-server MCP server](https://glama.ai/mcp/servers/groundroof/crehq-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/groundroof/crehq-mcp-server)

Score Badge

Copy to your README.md:

[![crehq-mcp-server MCP server](https://glama.ai/mcp/servers/groundroof/crehq-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/groundroof/crehq-mcp-server)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/groundroof/crehq-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server