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

Annotations cover readOnlyHint and idempotentHint, and the description adds value beyond them: it is free, it documents the auth mechanism (api_key arg or Authorization: Bearer fc_live_... header), and it discloses specific failure modes (400 on missing key, 401 on invalid key). That is meaningful behavior an agent cannot get from the annotation block.

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

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

Front-loads the most decision-relevant fact ('FREE') and organizes the rest into labeled sections, so it scans quickly. Slightly verbose with all-caps section headers and some repetition between the auth sentence and the parameter description, but nothing is wasted.

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

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

An output schema exists, so return values need no prose. Combined with clear usage conditions, auth requirements, and error codes, the description gives an agent everything needed to invoke this single-parameter read tool correctly.

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

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

Schema coverage is 100% and the schema already states the key is optional if the Authorization header is set, so the description largely restates parameter behavior. It mildly reinforces the header fallback but adds no format or validation detail beyond the schema. Baseline 3 for full coverage.

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

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

States a specific verb+resource ('Query the remaining prepaid credit balance... for a FranchiseData Pro API key') and names what it is not for. The sibling topup_credits is explicitly contrasted, so an agent can route without opening either schema.

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

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

Explicit WHEN TO USE ('before executing batch paid queries to verify sufficient funds'), WHEN NOT TO USE ('do not use for minting new keys or topping up funds'), and a named alternative ('use topup_credits'). All three guidance elements are present with the selecting condition.

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

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

Annotations only cover readOnly/idempotent/closed-world; the description adds the traits that actually matter for calling it: free of charge, no API key or balance required, a 60 req/min rate limit, and explicit 404 behavior for unrecognized routes. This is well beyond what the structured fields provide.

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

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

Front-loads the most decision-relevant fact ('FREE') and then chunks behavior and routing into labeled sections. Dense with no filler sentences; each clause carries a distinct operational fact.

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

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

An output schema exists, so return-value description is unnecessary. With the cost, auth, rate-limit, and error behavior all stated, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100% and the single 'endpoint' parameter is already documented with examples in the schema. The description restates the target as 'any REST API route' but adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Inspect/Describe) and resource (REST API route schema, auth, pricing) and explicitly scopes it to franchisedata.io endpoints. It clearly distinguishes itself from 'fetch_franchise_data' and the shortcut tools, so an agent can route between them without opening either schema.

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

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

Contains explicit WHEN TO USE, WHEN NOT TO USE, and ALTERNATIVES sections naming the sibling tools and the conditions that select them. Nothing about tool selection is left to inference.

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

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

Annotations only declare readOnly/idempotent/closed-world; the description adds the non-obvious operational facts an agent needs: a $0.003 paid call, atomic debit semantics, the required 'fc_live_...' key prefix, and a 402 response when balance is insufficient. This is real value beyond the structured fields, and the billing behavior does not contradict the readOnly annotation.

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

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

Front-loaded with cost and capability, then constraints, then routing — a sensible priority order with no filler sentences. The brand enumeration and ALL-CAPS section labels are dense but each clause carries distinct information.

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

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

An output schema exists, so return-shape explanation is unnecessary; the description fills the remaining gaps that structured fields do not (price, billing atomicity, auth key, 402 failure mode, usage routing). An agent has everything needed to call this correctly or route elsewhere.

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

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

Schema description coverage is 100% with examples for both brand and store_id, so the schema already carries the parameter burden. The description adds no format, canonicalization, or validation detail beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb (fingerprint) plus the exact resources targeted (POS hardware brands, KDS, online ordering gateways) and scopes it to a single store location. It explicitly names the sibling tools it is not (get_menu_pricing, starbucks_store_status), so an agent can disambiguate without opening a schema.

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

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

Explicitly structured as WHEN TO USE (tech competitive auditing, vendor share tracking, POS displacement prospecting), WHEN NOT TO USE with the correct alternatives named, and an ALTERNATIVES line routing get_menu_pricing and get_operator_intelligence to their proper cases. Nothing is left to inference.

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

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

Annotations already cover the read-only/idempotent safety profile, and the description goes well beyond them: per-request pricing ($0.002-$0.005), atomic balance debiting, required 'fc_live_...' key with sufficient balance, and a 402 failure mode. That is exactly the operational context an agent needs before invoking a paid, credential-gated call.

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

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

Front-loads the paid/cost signal and uses clear labeled sections (WHEN TO USE, WHEN NOT TO USE, ALTERNATIVES) that make it skimmable. It is dense and slightly long, but every sentence earns its place; no filler.

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

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

For a generic paid REST passthrough with an output schema present, the description covers everything the agent needs: cost, auth requirements, failure mode, and when to prefer typed alternatives. Return-value detail is correctly omitted since the output schema handles it.

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

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

Schema coverage is 100% with examples in every parameter description ('/api/brands/mcdonalds/locations', {'state':'CA',...}), so the schema carries parameter semantics. The description adds only the general notion of 'typed arguments' and does not extend path/params/api_key meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Execute) and resource (parameterized REST queries against franchisedata.io endpoints), and explicitly frames itself as a generic escape hatch. The agent can distinguish it from typed shortcut siblings without opening any schema.

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

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

Has explicit WHEN TO USE / WHEN NOT TO USE / ALTERNATIVES sections, naming four concrete sibling tools (get_fdd_item19, detect_tech_stack, get_operator_intelligence, mcdonalds_locations) and the condition that selects each. It even routes the agent to describe_endpoint first to verify routes.

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

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

Goes well beyond the readOnlyHint/idempotentHint/openWorldHint annotations by disclosing cost ($0.005), that the debit is atomic, the required 'fc_live_...' API key, and the 402 failure mode on insufficient balance. The $0.005 metering debit is a billing side effect of a read-only data operation, so it is consistent with readOnlyHint rather than contradicting it.

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

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

Front-loads cost and operation, then layers usage, exclusions, and alternatives in scannable labeled blocks. Every sentence carries routing or behavioral information with no filler.

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

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

An output schema exists, so return values need no prose. For a paid, authenticated search tool the description covers cost, auth, error behavior, scope limits, and sibling routing — everything an agent needs to call it correctly.

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

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

Schema description coverage is 100% and the schema already documents all four parameters with examples and defaults (radius default 10, max 50). The description restates the 50-mile cap and category use case but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource — a radial coordinate proximity search across 500 US restaurant franchise chains — plus scope (up to 50 miles) and return contents (geocoded locations, distance, brand classification). It is clearly distinguishable from siblings like mcdonalds_locations and search_brands.

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

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

Provides explicit WHEN TO USE (geographic competitive landscape, market density, multi-brand nearby search), WHEN NOT TO USE with named alternatives for each case (mcdonalds_locations for single-brand, search_brands for catalog metadata), and a dedicated ALTERNATIVES line including get_local_share_of_choice.

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

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

Annotations only declare readOnly/idempotent/openWorld, so the description carries real weight and delivers: it discloses the $0.010 charge, atomic debit behavior, the required 'fc_live_' API key, and the 402 response when balance is insufficient. These are operationally critical facts absent from the 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.

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

Front-loaded with cost and purpose, then cleanly sectioned by use/not-use/alternatives. Minor redundancy: the $0.010 charge is stated twice ('PAID ($0.010)' and 'Atomically debits $0.010'), which costs a little tightness but not clarity.

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

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

With an output schema present, return-value explanation is unnecessary, and the description already covers pricing, auth prerequisites, failure mode, and routing guidance. An agent has everything needed to invoke it correctly and budget for it.

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

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

Schema coverage is 100% and the single 'brand' parameter is fully documented in the schema with examples, so the description adds no further semantic detail. Baseline 3 is appropriate when the schema does all the work.

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

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

States a specific verb (Retrieve) and resource (regulatory FDD Item 19 financial disclosures), then enumerates the exact contents (AUV, quartile revenue tiers, royalty %, marketing fund %, capital requirements). This is enough to distinguish it from any sibling without opening a schema.

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

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

Explicit WHEN TO USE, WHEN NOT TO USE, and ALTERNATIVES sections name the substitute siblings directly: get_weekly_scorecard for store ops, get_menu_pricing for store pricing, search_brands for discovery. Nothing is left to inference.

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

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

Beyond the read-only/idempotent annotations, it discloses cost ($0.005), atomic debit semantics, required 'fc_live_...' key format, and the 402 failure mode for insufficient balance. This is exactly the operational context annotations cannot carry.

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

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

Front-loads cost and purpose, then structures use/avoid/alternatives into labeled clauses. Dense but every sentence carries routing or behavioral information.

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

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

With an output schema present, the description need not explain return values, and it covers cost, auth, failure mode, and sibling routing. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% with documented enums, so the baseline is 3. The description adds no parameter-level detail (no explanation of daypart/platform/store_id semantics) beyond naming the data domains.

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

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

States a specific verb and resource ('Query local digital shelf telemetry') and enumerates the concrete data returned: price gaps, ETA disparities, organic vs sponsored placement. It is clearly distinguishable from siblings like get_fdd_item19 or get_menu_pricing.

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

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

Provides explicit WHEN TO USE (delivery channel share loss, competitor promotion surges, aggregator markup disparities), WHEN NOT TO USE (static national FDD disclosures -> get_fdd_item19), and ALTERNATIVES (recommend_local_action, get_menu_pricing). Routing is fully specified.

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

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

Annotations cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), and the description adds substantial context beyond them: a $0.003 cost, atomic debit semantics, the required 'fc_live_...' API key format, and the 402 insufficient-balance failure mode. This is exactly the billing/auth behavior an agent needs and cannot get from annotations.

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

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

Front-loads the paid cost and core capability, then usage, then routing, all in a compact block. Slight redundancy in stating the $0.003 price twice ('PAID ($0.003)' and 'Atomically debits $0.003'), which keeps it just short of a 5.

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

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

For a two-param, paid, read-only lookup with an output schema present, the description covers cost, auth, failure mode, and routing without needing to describe return values. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% with only two parameters, so the schema already documents 'brand' (with slug examples) and 'store_id' (with example ID). The description adds no parameter-level syntax or format detail beyond that. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States specific verbs and resources — extract localized menu prices, benchmark variances, identify delivery markups — and names the exact siblings it is not (get_local_share_of_choice, get_fdd_item19). An agent can distinguish it from every sibling without opening a schema.

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

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

Explicit WHEN TO USE (pricing audits, inflation tracking, margin variance), WHEN NOT TO USE with the alternative named for the excluded case, and an ALTERNATIVES line routing to two specific sibling tools by use case. Nothing is left to inference.

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

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

Annotations cover the safety profile (readOnlyHint/idempotentHint/openWorldHint), but the description adds substantial value: pricing ($0.005), the atomic debit, the required 'fc_live_...' API key, and the 402 insufficient-balance behavior. The only tension is the debit side effect against readOnlyHint, though this concerns billing rather than domain-data mutation, so it is supplemental rather than contradictory.

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

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

Front-loads the cost and auth requirement, then sections usage guidance cleanly; nearly every sentence earns its place. Slight redundancy in naming get_fdd_item19 twice (WHEN NOT TO USE and ALTERNATIVES) keeps it just below top marks.

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

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

For a paid, key-gated read tool with an output schema, the description covers everything an agent needs: cost, auth, error behavior, selection rule, and routing to alternatives. Return-format details are correctly left to the output schema.

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

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

Schema description coverage is 100% and the schema already documents brand, store_id, and operator_id as well as the OR relationship. The description restates the selection rule ('operator_id' OR both 'brand' and 'store_id'), which is helpful confirmation but adds little beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Retrieve corporate franchisee entity trees, operating LLCs, portfolio unit counts, and executive leadership contacts') and names concrete examples (Flynn Group, Carrols). It is immediately distinguishable from sibling lookups like get_fdd_item19 or detect_tech_stack.

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

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

Explicit WHEN TO USE, WHEN NOT TO USE, and ALTERNATIVES sections name the exact sibling tools to route to (get_fdd_item19 for Item 19, semantic_vector_search for fuzzy operator search, detect_tech_stack for hardware). No condition is left to inference.

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

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

Annotations cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), and the description goes well beyond them with the price ($0.010 atomic debit), the required 'fc_live_...' API key, the default-week fallback, and the specific failure modes (404 no scorecard, 402 insufficient balance). This is exactly the billing/auth/error context annotations cannot express.

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

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

Front-loads the price, then purpose, constraints, and finally the routing sections, so the most decision-relevant facts come first. Slightly repetitive in stating the price twice ('PAID ($0.010)' and 'Atomically debits $0.010'), but overall every block earns its place.

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

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

With an output schema present, return values need not be described; the description instead supplies cost, auth requirements, default behavior, error codes, and full sibling routing. Nothing an agent needs to invoke this paid tool correctly is missing.

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

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

Schema description coverage is 100%, so both parameters already carry their own documentation. The description restates the week default ('latest evaluated week') but adds no syntax or format detail beyond what 'week' and 'store_id' already document, so the baseline of 3 applies.

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

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

States a specific verb (Retrieve) and a precisely scoped resource (the standardized 6-Question Weekly Operating Review Scorecard for a restaurant location), even enumerating the six sections it contains. An agent can distinguish it from every sibling (e.g. get_fdd_item19, franchise_search_near) without opening a schema.

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

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

Explicit WHEN TO USE (weekly operational store diagnostics, executive unit reviews, root-cause sales analysis) and WHEN NOT TO USE clauses that name the correct alternatives ('franchise_search_near' for location search, 'get_fdd_item19' for brand FDD). An ALTERNATIVES line further routes 'recommend_local_action' and 'get_local_share_of_choice' to adjacent use cases.

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

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

Annotations only declare the safety profile (readOnly, idempotent, closed-world); the description adds material context the annotations cannot convey — the $0.003 atomic debit, the required 'fc_live_...' API key, and the 402 insufficient-balance behavior. This is exactly the kind of paid-endpoint disclosure that prevents failed calls.

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

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

Front-loaded with cost and capability, then organized into UPPERCASE routing headers — efficient and scannable. The filter list is slightly redundant with the schema, keeping it just short of a 5.

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

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

An output schema exists so return values need not be explained, and the description covers cost, auth, error handling, and routing. Nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema description coverage is 100%, so every parameter (zip, city, limit, state, drive_thru) is already documented with examples in the schema. The description only restates the filter dimensions at a high level, adding no new syntax or semantics. Baseline 3 applies.

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

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

States a specific verb (search) and resource (McDonald's store locations) with the exact filter dimensions, and explicitly names the sibling it is not (franchise_search_near). An agent can distinguish it from cross-brand siblings without opening any schema.

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

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

Contains explicit WHEN TO USE, WHEN NOT TO USE, and ALTERNATIVES clauses, naming franchise_search_near and search_brands as the correct tools for adjacent use cases. Routing is fully determined.

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

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

The description states the tool 'PAID ($0.005)... Atomically debits $0.005', a state-mutating financial side effect that contradicts the provided readOnlyHint=true annotation, and per-call charging also conflicts with idempotentHint=true. Although it usefully discloses auth requirements ('fc_live_...' key) and error semantics (404 no scorecard, 402 insufficient balance), the explicit contradiction with the safety/idempotency annotations forces the floor score.

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

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

The description is dense but well front-loaded, leading with price/behavior, then constraints, then WHEN TO USE / WHEN NOT / ALTERNATIVES. Nearly every clause earns its place, though the repeated pricing emphasis ('PAID ($0.005)' plus 'Atomically debits $0.005') is somewhat redundant.

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

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

With an output schema present, return values need not be explained, and the description still covers auth, billing, and two error codes plus routing. It is nearly complete for a one-parameter tool; the only real gap is that the behavioral picture conflicts with its own annotations.

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

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

Schema description coverage is 100% and there is a single store_id parameter already documented in the schema, so the baseline is 3. The description adds no format or constraint detail about store_id beyond what the schema provides, but it doesn't omit anything either.

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

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

The description uses a specific verb and artifact ('Synthesize local competitor shifts and digital funnel gaps to formulate a single... tactical intervention with matched holdout test design'), which is far more precise than the name alone. It is clearly distinguishable from siblings like get_weekly_scorecard and get_local_share_of_choice, which are named as different outputs.

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

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

It carries explicit 'WHEN TO USE', 'WHEN NOT TO USE' (routing broad search to franchise_search_near and mapping to get_operator_intelligence), and 'ALTERNATIVES' sections naming specific siblings. An agent has no inference left to do about tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, but the description adds cost ('FREE'), auth requirements ('no API key or balance'), and a concrete rate limit (60 req/min). That is exactly the extra behavioral context annotations cannot convey.

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

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

Front-loaded with the essential verb, resource and cost, then cleanly partitioned into WHEN TO USE / WHEN NOT TO USE / ALTERNATIVES. Dense but every clause carries routing or behavioral information.

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

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

An output schema exists, so return values need not be explained; the description nonetheless sketches the return shape (unit counts, category, pricing). Combined with the sibling routing and rate-limit info, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by naming the queryable facets (name, concept, sector, category) and the default behavior when query is omitted, though 'concept, sector' drifts slightly from the schema's 'name, category, slug' wording.

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

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

States a specific verb ('Search and discover') and resource ('indexed restaurant brands across the 500 US franchise database'), plus the searchable dimensions. An agent can immediately distinguish it from siblings like semantic_vector_search or franchise_search_near.

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

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

Explicit WHEN TO USE (discovering brand slugs, verifying catalog indexation), WHEN NOT TO USE with named alternatives for each excluded case (franchise_search_near, mcdonalds_locations, get_fdd_item19, semantic_vector_search), and an ALTERNATIVES line. This is the gold standard for routing.

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

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

Discloses pricing ($0.005 debit), auth requirement ('fc_live_...' key), the 402 insufficient-balance failure mode, default type behavior, and the conditional applicability of the brand parameter. These are side-effect and precondition details that annotations (readOnly/idempotent) do not cover; note the billing debit is a nuance against readOnlyHint but is a billing concern rather than a data mutation.

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

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

Front-loads the cost signal and is organized into purpose, mechanics, and routing sections. Slightly redundant in restating the $0.005 debit twice ('PAID ($0.005)' and 'Atomically debits $0.005'), but no sentence is wasted.

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

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

With an output schema present, return values need no explanation, and the description covers cost, auth, failure codes, defaults, and routing for a 4-parameter tool. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents type, brand, limit, and query semantics. The description adds only the type default ('operators' if omitted) and the brand-only-with-menu rule, both of which are already stated in the schema descriptions, so it does not meaningfully exceed the schema.

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

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

States a specific verb and resource ('high-dimensional cosine similarity semantic vector search across multi-unit operators and menu items using embeddings') and distinguishes itself from keyword and proximity siblings by name. An agent can identify the tool's function without opening the schema.

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

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

Explicit WHEN TO USE with concrete example queries, WHEN NOT TO USE naming two sibling tools by name, and an ALTERNATIVES line mapping each sibling to its purpose. Routing is fully determined.

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

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

Annotations already declare readOnly/idempotent/openWorld=false, and the description adds substantial context beyond them: the $0.002 atomic debit from prepaid balance, the required 'fc_live_...' API key, and the 404/402 error semantics. This is exactly the extra behavioral layer the dimension rewards.

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

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

Front-loaded with the core capability, cost, and auth before the WHEN TO USE/WHEN NOT blocks. Dense but nearly every sentence earns its place; minor redundancy in stating the paid cost in both the leading tag and the body.

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

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

For a single-optional-param read tool with an output schema, the description covers everything an agent needs: cost, auth requirement, default behavior, and error outcomes. Return-value details are correctly left to the output schema.

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

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

Schema coverage is 100% and there is only one optional parameter, so the schema already documents the store_id format and default behavior. The description restates the default-to-first-indexed-store behavior without adding format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Retrieve live operating status, weekly schedule, and current open/closed state for a specific Starbucks store') with a clearly bounded scope. It is instantly distinguishable from siblings like franchise_search_near or track_brand_changes, which it names explicitly.

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

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

Provides explicit WHEN TO USE ('verify whether an individual store is currently open or view its schedule'), WHEN NOT TO USE (not for fleet-wide discovery), and ALTERNATIVES naming two specific sibling tools with the conditions that select them. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, but the description adds meaningful context beyond them: it discloses the mutation's effect (creates or updates database credentials), that no prior authentication is required, the $1–$500 bounds, and the returned key/balance shape. It does not restate non-idempotency explicitly, a minor gap.

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

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

Front-loaded with the core action, then scoped by labeled sections that make scanning easy. The only waste is mild overlap between the WHEN NOT TO USE and ALTERNATIVES clauses, both citing check_balance.

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

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

For a two-parameter mutation with annotations and an output schema, the description covers everything an agent needs: mode selection, limits, auth requirement, and mutation effect. Return-value detail is not required since an output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real behavioral meaning to the optional parameter: passing 'api_key' tops up, omitting it mints a fresh key. That conditional semantics is the crux of correct invocation and is not spelled out as clearly in the schema alone.

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

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

States a specific verb+resource with dual scope: 'Deposit prepaid credits into an existing API key or mint a new key.' It clearly distinguishes the two modes of operation and names a sibling (check_balance) so an agent can route correctly without opening a schema.

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

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

Explicit WHEN TO USE (exhausted credits, new agent session), WHEN NOT TO USE (balance inspection only), and ALTERNATIVES (check_balance) sections leave nothing to inference. The condition selecting the alternative is stated directly.

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

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

Beyond the annotations, it discloses cost ($0.003), atomic debit semantics, the required 'fc_live_...' key prefix, and the 402 insufficient-balance failure mode — none of which is inferable from the schema or annotations. This is exactly the side-effect and auth context the structured fields cannot carry. The billing debit is an accounting side effect on the account rather than a mutation of the fleet-event data, so it does not conflict with readOnlyHint=true.

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

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

Front-loaded with the paid cost and atomic debit, then the when-to-use routing — good ordering. The WHEN NOT TO USE and ALTERNATIVES sections restate the same 'starbucks_store_status' pointer twice, which is mild redundancy.

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

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

For a two-parameter read tool with an output schema, the description covers everything the agent needs: purpose, cost, auth, failure mode, and sibling routing. Return-value shape is delegated to the output schema, so nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by glossing 'closure' as 'permanent closures' (distinguishing it from the live-hours sibling) and enumerating the three event types in prose. It does not, however, explain the brand slug format beyond what the schema already states.

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

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

States a specific verb and resource — auditing recent fleet events (openings, closures, relocations) for a given brand — and the scope is unambiguous. It explicitly differentiates itself from 'starbucks_store_status' (live hours) and 'franchise_search_near' (current open units), so an agent can select it without opening schemas.

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

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

Contains explicit WHEN TO USE (footprint expansion, net unit growth velocity, distress/closure detection), WHEN NOT TO USE (real-time daily hours), and named ALTERNATIVES with the conditions that select each. This is a textbook routing block.

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