Loppee

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

Beyond annotations (readOnly=false, idempotent=true), the description discloses key behavioral traits: authentication requirements, no charge to seeker, private resume storage with scoped short-lived signed URLs. This adds substantial context for an agent evaluating side effects and security.

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?

Three sentences deliver the main action, prerequisites, cost, and security details without fluff. Front-loaded purpose ensures immediate understanding. Every sentence adds necessary information.

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

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

For a complex write operation with nested parameters and an output schema, the description covers purpose, auth, constraints, cost, and data handling. It is complete enough for an agent to correctly invoke the tool without further clarification.

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

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

Schema description coverage is 0%, so the description compensates well. It explains the resume parameter in detail (base64 PDF/DOC/DOCX, private storage) and the account_id requirement (matching key). job_id and cover_note are left to name inference, but the core complex parameters are enriched.

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

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

The description clearly states the action ('Apply to an active Loppee job'), specifies the actor ('on behalf of the calling customer account'), and differentiates from sibling tools like list_job_applications, withdraw_job_application, and update_job_application_status. The verb+resource+scope is specific and unambiguous.

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

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

Provides clear context including prerequisites (customer personal agent key with matching account_id and allowed_actions), the restriction to 'active' jobs, and cost implications. Does not explicitly name alternatives, but the context makes it obvious this is the create-application action among siblings.

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

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

The description adds substantial behavioral detail beyond the annotations: it explains the idempotent outcome ('clearing when nothing is saved returns available=false'), clarifies that provider IP remains neutral and cannot trigger local placements or impressions, and gives the exact follow-up prompt for the next local search. This aligns with and elaborates on the idempotentHint and openWorldHint annotations without contradiction.

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

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

The description is front-loaded with the primary action and then provides behavioral details in a logical order. The embedded quote for the next local search is longer than typical tool guidance, but it serves a concrete interaction purpose. No words are wasted, though it could be more compact.

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

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

Given the tool's low complexity (one parameter), full schema coverage, existing output schema, and annotations, the description is complete. It covers the operation, idempotency, side effects on local search behavior, and the exact next-step prompt. Nothing important is missing for an agent to select and invoke this 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?

The single parameter account_id is fully described in the schema with a clear instruction to confirm via get_agent_identity. The description mentions 'calling customer's,' which loosely connects to the parameter, but it does not add new semantic meaning beyond the schema's description. Per the baseline for high schema coverage, a 3 is appropriate.

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

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

The description opens with a specific action, 'Remove the calling customer's saved service location,' which clearly identifies the tool's verb and resource. It distinguishes this from sibling tools like set_my_location and get_my_location by using 'clear'/'remove' as the unique operation. The scope ('calling customer's') adds useful context.

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

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

The description implies the tool is used to clear a previously saved location and adds post-clear follow-up guidance, but it never explicitly contrasts this tool with set_my_location or get_my_location. There is no 'use this tool when X, otherwise use Y' guidance, though the action verb makes the primary use case clear.

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 read-only and non-destructive behavior. The description adds substantial behavioral context: payment never affects reviewer quality, exposure-plan effects on discovery reach, and explicit non-effects on publication, verification, reputation, and ranking. This goes well beyond the annotations and clarifies non-obvious data provenance policies.

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 front-loaded with the core point, but the payment-related sentences are verbose and arguably tangential for a comparison tool. For example, the exposure-plan explanation and the Loppee Jobs clarification could be condensed. Several sentences repeat similar non-effects, making the description longer than necessary.

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

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

Given the tool's complexity (read-only comparison with payment-related caveats), the description thoroughly covers the key constraints: published-only, registry unavailability, request-order significance, and non-influence of payment on quality metrics. Output schema exists, so return values don't need explanation. The completeness is high, though the verbosity slightly detracts.

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% for the single param, so baseline is 3. The description adds meaning by stating 'in request order', clarifying that the order of business_ids affects the comparison output—an important detail not present in the schema description. This extra semantic value pushes the score to 4.

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

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

The description clearly states the verb 'Compare' and the resource 'published businesses', and adds scope with 'only published businesses' and 'in request order'. It distinguishes from sibling tools like lookup_business by implying multi-business comparison, but 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.

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

The description implies when to use the tool ('Compare published businesses only') and provides a negative constraint ('Registry rows remain unavailable on this tool'), but it does not explicitly state when to prefer this tool over siblings like search_businesses or recommend_businesses, nor does it name alternatives.

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 tool has annotations (readOnlyHint=false) indicating mutation, and the description adds important behavioral context: the request is 'short-lived', has 'browser fallback', authorizes 'local category/recommendation reach and Sponsored exposure' upon approval, and crucially states 'The assistant receives readiness and normal business results, never latitude or longitude.' It also details the polling flow. No contradiction with annotations.

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

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

The description is six sentences but each conveys necessary details: purpose, approval effect, polling workflow, conditional URL display, output privacy, and key requirement. It is front-loaded and free of filler. It's slightly longer than minimal but all content is functional.

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?

Despite having no parameters and relying on the output schema, the description provides a complete operational picture: it explains the purpose, prerequisites, step-by-step workflow, conditional behavior, and privacy guarantee. It also notes the browser fallback. This is sufficient for an agent to use the tool correctly.

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

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

The input schema has zero properties, so schema description coverage is 100% and there are no parameters to explain. The description mentions poll_after_seconds and location_url, which are likely output fields, not parameters. Baseline 4 applies as no parameter compensation is needed.

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

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

The description uses the specific verb 'Create' with the resource 'location_handoff' and explains it's a 'short-lived current precise-location request with a browser fallback.' This clearly distinguishes it from sibling tools like get_location_handoff, which retrieves the result. The title 'Ask User for Precise Location' reinforces the purpose.

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

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

The description provides explicit operational guidance: 'Wait poll_after_seconds, then call get_location_handoff once' and 'Only if that poll is still awaiting_user should you show or send location_url.' It also states a prerequisite (active database-backed customer personal-agent key). However, it does not explicitly compare against alternatives like set_my_location or get_my_location, 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.

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

Annotations already declare destructive and non-read-only behavior. The description adds valuable context: ownership of rejection reasons, conditional rules for source_url/source_authority based on verification_method, the restriction that official_record_not_found only applies to official_source_manual, and the reauthorization/class-derivation behavior. No contradiction with annotations.

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

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

The description is a single dense paragraph with no visual structure. It front-loads the core purpose but then presents many rules in a stream of sentences. Each sentence adds information, but the format is not scannable, making it harder for an agent to extract the key constraints quickly.

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

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

Given 14 parameters, annotations, and existing output schema, the description covers the most important behavioral rules: authorization needs, per-method requirements, legacy compatibility, and separation of internal vs owner-facing reasons. It omits return behavior and error cases, but those are likely covered by the output schema. The overall coverage is strong for the tool's complexity.

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 only 21%, so the description carries the burden for parameter semantics. It explains key interactions: owner_reason_code is required for rejection but forbidden for approval, source_authority and source_url are required for official_source_manual and forbidden for document_review, and valid_until is the approval validity window. It does not disambiguate every parameter, but it covers the most conditional ones.

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

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

The description opens with a specific verb-resource pair: 'Approve or reject one current entity/license submission'. It clearly distinguishes this from sibling list tools (e.g., list_admin_manual_verification_submissions) by stating this tool executes the decision rather than merely listing submissions.

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

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

The description gives context for when this tool is applicable (manual authority decisions) and prerequisites such as the complete_manual_verification action, but it never explicitly contrasts it with alternatives or states when not to use it. The reader must infer that siblings like list_admin_manual_verification_submissions or get_admin_verification_case serve different purposes.

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

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

The description adds behavioral context beyond the readOnlyHint annotation by explaining that the tool works only for published businesses and why a business_id alone is insufficient to reconstruct the prior category, location, and fallback context. It does not, however, describe error handling or fallback behavior when an unpublished business is passed.

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

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

The description is two sentences, front-loaded with the core purpose, and the second sentence explains a key constraint without unnecessary verbosity. Every sentence 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 one parameter, an output schema, and clear annotations, the description provides sufficient context for an agent to invoke the tool correctly. It explains the tool's scope, limitations, and relationship to recommendation rationale, making it complete for the tool's complexity.

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

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

The schema covers business_id with a description, and the tool description adds context about the published-only nature and the v3 class, which helps clarify the parameter's use. Since schema coverage is 100%, the extra detail in the description provides modest added value.

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

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

The description clearly states the tool's purpose: 'Explain one published business's v3 class and exact disclosure.' It uses a specific verb and resource, and distinguishes itself from recommendation rationale tools by stating that the rationale stays on the category recommend row.

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

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

The description explicitly states when to use the tool (for published businesses) and when not to use it (for recommendation rationale, which remains on the category recommend row). It provides a clear exclusion and points to an alternative location, satisfying the 'when/when-not/alternatives' criterion.

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?

While annotations already declare readOnlyHint=true, the description adds specifics: 'never changes billing, placement, verification, or publication' and the auth requirement. This goes beyond the annotations and gives valuable operational context, though it doesn't address potential side effects like rate limits or data bounds.

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

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

The description is two sentences, front-loaded with the main purpose, and every sentence adds unique value. There is no redundancy or filler.

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

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

The tool is simple with one optional parameter and an output schema, so return values are covered. The description adequately conveys auth requirements and read-only behavior. However, the missing explanation of the 'days' parameter leaves a gap for an agent to understand default behavior and expected input semantics, making it not fully complete.

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

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

Schema description coverage is 0%, and the description does not mention the 'days' parameter at all. The schema only provides enum values (7, 30, 90, 'all') without explaining what the parameter controls or how it affects the response. The description fails to compensate for the low schema 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?

The description clearly states the tool reads bounded Back-office operational and projected-revenue analytics. This is a specific verb ('Read') and resource ('Back-office analytics'), but it does not explicitly distinguish itself from similar siblings like get_admin_overview, so it falls short of a 5.

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

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

The description provides clear context, including a required authentication condition (team/admin-agent key with view_financial) and states the tool is read-only. However, it does not explicitly name alternatives or exclusions, so it lacks full when-to-use vs. not guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context by specifying the exact scope (queue totals and launch checks) and required authorization, which annotations do not convey. No contradiction with 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?

Two concise sentences: the first states the action and resource, the second covers access requirements. No filler or redundant repetition of schema/annotation information; every word 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?

Given the tool's simplicity (no params, output schema exists, readOnly annotation), the description effectively covers what the tool does, its scope, and access control. It lacks explicit guidance on differing from similar admin tools, but this is a minor gap for a straightforward overview tool.

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

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

The tool has zero parameters, so schema coverage is 100% and the description inherently compensates. The baseline for 0 params is 4; the description doesn't need to explain parameters, and it doesn't, which is appropriate.

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

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

The description clearly states the tool reads 'Loppee back-office queue totals and launch checks', using the specific verb 'Read' and distinct resource. This separates it from sibling admin tools like get_admin_analytics (analytics) or list_admin_businesses (lists), which serve different purposes.

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

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

The description provides access prerequisites (team/admin-agent key with 'view' allowed_actions) and explicitly excludes consumer/business-owner keys, but it does not explain when to use this tool versus other back-office tools. No alternatives or when-not-to-use guidance is given, leaving the decision to the agent based solely on the resource name.

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=true and destructiveHint=false. The description adds valuable context beyond these: authentication requirements (team/admin-agent key with view), the exact response projection (minimized v3), and that it 'never grants authority to change the business class,' which clarifies the read-only nature and potential side effects. This is meaningful behavioral disclosure beyond the structured metadata.

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

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

The description is concise and well-structured. It leads with the primary action in the first sentence and adds necessary context in the second. Every sentence provides useful information without redundancy or fluff.

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

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

Given the tool's simplicity (one read-only parameter, output schema available), the description covers all essential aspects: what it does, the required auth, the response format, and the lack of write authority. No further context is needed for an agent to select and invoke this 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?

The input schema has only one parameter (business_id) with no description, so schema coverage is 0%. The description compensates by explicitly saying 'by business_id,' which clarifies that the parameter identifies which case to open. For a simple string ID, this is sufficient and adds meaning beyond the schema.

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

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

The description clearly states a specific action: 'Open one audited verification case file by business_id.' It identifies the resource (verification case file) and the key parameter (business_id). The inclusion of 'one' distinguishes it from the sibling list_admin_verification_cases, making its unique purpose clear.

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

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

The description provides clear context: this tool fetches a single case file by ID, which implies it is used when you need a specific case rather than a list. It also notes a prerequisite (team/admin-agent key with view). However, it does not explicitly name alternatives 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.

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is known. The description adds value by enumerating the specific contents returned (contract, endpoints, policy rules, available MCP tools), which goes beyond the generic 'Return' statement. No contradictions found.

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

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

The description is a single concise sentence, front-loaded with the verb 'Return', and contains no extraneous words. Every phrase adds specificity.

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?

This is a simple, zero-parameter, read-only introspection tool with an output schema present. The description sufficiently covers the return content, and the output schema handles the structural details. No further context is needed for an agent to select and invoke this 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?

The tool has zero parameters, so there is nothing to explain. The baseline for zero-parameter tools is 4, and the description does not need to add parameter details.

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

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

The description uses a specific verb 'Return' and clearly identifies the resource as the Loppee agent contract, endpoints, policy rules, and available MCP tools. This distinguishes it from the sibling tool get_agent_identity, which focuses on identity rather than capabilities.

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

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

The description implies the tool is used to retrieve the agent's capabilities and configuration, which is clear context for a zero-parameter introspection tool. It does not explicitly name alternatives or exclusions, but the purpose is self-evident from the resource list.

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?

While annotations already indicate readOnlyHint and destructiveHint, the description adds valuable behavioral context: it reveals that the principal supplies the external agent and Loppee issues scoped access, and it explicitly states the error condition ('returns an auth error when the key is missing or revoked'). This goes beyond the structured annotations.

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

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

The description is three sentences long, front-loads the core purpose, and each sentence earns its place: purpose/returns, usage context, and authentication/error behavior. There is no redundancy or filler.

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

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

Given the tool has no parameters and an output schema exists, the description covers all necessary aspects: what it does, when to call it, the auth requirement, and error behavior. It is a complete and self-sufficient description for an AI agent to select and invoke correctly.

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

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

The tool has zero parameters, and the description appropriately focuses on the authentication context (X-LOPPEE-API-Key or Bearer token) rather than inventing parameters. This adds meaningful information about how the tool is invoked, surpassing the baseline of 4 for zero-parameter tools.

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

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

The description clearly states the tool's function: 'Identify the calling agent from its API key' and lists the specific return fields (account_id, scope_kind, label, allowed_actions). This is a specific verb+resource definition that distinguishes it from siblings like get_agent_capabilities by emphasizing identity and permission discovery.

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

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

The description explicitly states when to use the tool: 'Call this first to confirm a key is wired correctly and to discover this agent's permissions before attempting any write tool.' It also implies when not to use it (not for write operations) and provides a clear directive for sequencing. This goes beyond a vague hint.

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 readOnlyHint=true annotation, the description discloses that every review remains visible, including unqualified legacy reviews with quality_ranking_weight=0. It also defines 'verified reviewer' as Passkey/phone verification, explicitly noting it does not prove a transaction or government identity — an important interpretation pitfall. This adds meaningful behavioral context beyond what annotations alone 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?

The description is five sentences and about 80 words, with the core purpose in the first sentence and supporting semantics in the rest. While somewhat dense, each sentence adds value, covering visibility guarantees, quality ranking semantics, and verification caveats. It is appropriately sized for the domain complexity.

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

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

Given the tool's domain complexity (verification vs. interaction evidence, legacy reviews), the description covers eligibility, review visibility, field semantics, and verification limits. The presence of an output schema means return structure is documented elsewhere, so the description need not duplicate that. It fully equips an agent to understand the tool's data and caveats.

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

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

The schema already provides full descriptions for all four parameters (business_id, page, limit, ratings) with 100% coverage, so the baseline is 3. The description does not add parameter-level detail, but it clarifies output field semantics like quality_ranking_weight, which indirectly informs how filters might be used. No additional parameter syntax is needed.

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

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

The description opens with 'Read public reviews for a published business or visible Registry-page business,' which clearly identifies the resource (public reviews) and verb (read). This differentiates it from sibling tools like lookup_business or get_trust_card, which target other business data. The eligibility criterion further refines the scope.

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 explicitly states the conditions under which the tool applies: published or visible Registry-page businesses, implying it should not be used for hidden/unpublished listings. It does not name alternative tools, but for the specific function of reading reviews, no sibling is a direct substitute. This gives the agent a clear contextual trigger for invocation.

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 readOnlyHint and idempotentHint annotations, the description adds crucial behavioral context: it returns only status/expiry, never coordinates, and references the handoff lifecycle ('Once ready'). This is valuable transparency for a tool that could otherwise be mistaken for a location getter.

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?

Three terse sentences: purpose, return behavior, and downstream usage. Every sentence carries distinct information, front-loaded for quick scanning. No redundant or filler content.

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

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

For a simple single-parameter read-only tool with a full output schema and 100% schema coverage, the description explains the tool's role in the larger handoff flow and clarifies the non-return of coordinates. It is complete for an agent to select and invoke 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% with a clear description of handoff_id as an opaque UUID from create_location_handoff. The description adds extra meaning by specifying how the id should be used downstream (renamed to location_handoff_id), which is not in the schema. This enhances understanding beyond the structured field.

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 ('Check') and resource ('current precise-location authority'), clearly distinguishing this from location retrieval tools like get_my_location. It also explicitly states what it returns (status and expiry) and what it never returns (coordinates), leaving no ambiguity about its function.

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

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

The description clearly indicates this tool is for checking approval status and provides downstream usage instructions ('pass handoff_id as location_handoff_id to...'). It implicitly excludes coordinate retrieval with 'never returns coordinates,' but does not explicitly name alternative tools or provide when-not-to-use scenarios beyond that.

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 indicate read-only and idempotent behavior. The description adds critical behavioral details: it never returns ZIP, address, latitude, or longitude, and specifies which location types authorize actions. No contradiction with annotations.

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

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

The description is a single, dense paragraph that covers all necessary aspects. It is front-loaded with the core return specification, but the length is justified by the behavioral complexity. Slightly verbose but efficient given the nuance.

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 sufficiently covers return values, constraints, and usage context. It does not need to detail output structure. The description is complete for a safe-location-options tool.

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

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

The only parameter, account_id, is fully described in the input schema (100% coverage). The description adds context by stating that the key must be an 'active scoped consumer personal-agent key,' extending the schema's description.

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

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

The description clearly states that the tool returns the calling customer's safe Home metadata, opaque saved_location_ref, current-location handoff availability, and provided city/ZIP context. It explicitly lists what is never returned, distinguishing it from sibling tools like get_my_location or get_location_handoff.

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

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

The description provides explicit when-to-use guidance, including exact phrasing to ask the user and conditions under which data authorizes discovery (e.g., current or Home with kind=saved_exact). It also notes the requirement for an active scoped consumer personal-agent key, covering prerequisites and contextual usage.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, and the description adds meaningful behavioral context: it never returns ZIP/address/lat/long, returns only safe subsets, and states that discovery location never affects business verification, review authority, review reputation, or recommendation eligibility. No contradiction with annotations.

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

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

The description is front-loaded with its alias and return limitations, then provides a user prompt and policy caveats. It is somewhat verbose due to the quoted question and multiple clauses, but every sentence carries substantive guidance rather than filler.

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

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

Given one fully documented parameter, an output schema, and rich annotations, the description covers all necessary context: safe behavior, authorization rules, and what the tool can/cannot return. No meaningful gaps remain.

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

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

The schema description for account_id is complete (100% coverage) and already instructs to confirm with get_agent_identity. The tool description adds no parameter-specific detail, so baseline 3 is appropriate.

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

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

The description states a specific verb+resource ('Get Safe Location Choices') and clearly identifies itself as a backward-compatible safe alias for get_location_options. It explicitly enumerates the exact return scope (availability, safe labels, precision metadata, opaque references) and what it never returns, distinguishing it from siblings.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'Only current or saved_exact authorizes local category/recommendation reach' and 'Another city/ZIP is for area context or business-name lookup only.' It also includes an exact user-facing prompt, giving clear operational direction.

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 mark readOnlyHint=true, but the description goes far beyond by explaining the real-world impact of plan data: editing prices cannot change verification/reputation, and payment only affects discovery reach under specific conditions. It also clearly separates Loppee Jobs billing. This is rich, non-obvious context that substantially aids correct interpretation.

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 front-loaded with the core purpose, but it becomes repetitive. Sentences 2 and 4 restate nearly the same list of unaffected attributes ('publication, verification class, review authority, reputation, moderation, class ordering'). This redundancy could be trimmed without losing meaning, making it longer than necessary for a no-parameter getter.

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 no parameters and an existing output schema, the description fully covers what the tool returns and the semantic meaning of its contents. It explains the scope of exposure plans, the effects of payment, the separation of Loppee Jobs, and what the data does not influence. Nothing essential 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?

The tool has zero parameters, so there is nothing for the description to explain. Per the rubric, 0 params earns a baseline of 4. The description adds no parameter details because none are needed.

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

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

The description opens with a clear verb ('Return') and specific resource ('Loppee's published exposure plans, feature bullets, branch add-ons, and promotions'). This distinguishes it from all sibling tools, none of which target pricing plans. Even with the extra caveats, the primary purpose is unmistakable.

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?

Usage is implied by the getter name and read-only nature. The description clarifies what the plans do and do not affect, which indirectly tells when this data is relevant, but it offers no explicit alternatives or exclusion criteria. For a simple getter, this is adequate.

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 indicate read-only and non-destructive behavior, lowering the bar. The description adds valuable behavioral context: the same Trust Card contract applies to both, Registry cards retain exact claim status/disclosure, remain outside published classes, and never fabricate missing facts. This goes beyond the 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?

Two sentences, front-loaded with the primary action, and each clause carries essential information without redundancy. The structure is compact and highly readable.

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

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

The description is fully self-contained for the tool's purpose, covering both business types, the identifier constraints, and the behavioral guarantees. With an output schema present, return values need no explanation, and the description addresses all critical context for correct invocation.

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 baseline is 3. The description adds meaningful semantics by clarifying that domain_key is restricted to published-only businesses, which is not evident from the schema's simple 'Normalized domain key' description. This enhances parameter understanding.

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

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

The description clearly states the tool's function: 'Fetch the public v3 Trust Card' with a specific resource and scope. It distinguishes between business_id and domain_key and covers both published and Registry-page businesses, making it distinct from sibling tools like lookup_business.

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

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

Provides clear usage context by explaining that business_id works for both published and visible Registry-page businesses, while domain_key is published-only. This is an implicit exclusion that guides selection, though it does not explicitly name alternatives.

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

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

The description adds meaningful context beyond the annotations: 'never grants ownership or changes a claim' reinforces the readOnlyHint and clarifies that listing does not mutate claims. It also discloses the auth requirement (review_intake), which is not in the schema or annotations. No contradiction found.

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

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

The description is two sentences: the first states the action and scope, the second states requirements and a safety guarantee. It is concise, front-loaded, and every sentence 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?

The tool is a simple list operation with an output schema covering return values. The description covers purpose, auth, and read-safety. It does not explain filter semantics, but the enum values ('open'/'all') are self-evident, and the pagination parameters are straightforward. Sufficiently complete for this complexity.

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

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

The schema has no descriptions for limit, filter, or offset (0% coverage), and the description provides no parameter semantics. While the parameter names are somewhat self-explanatory, the description adds no value for these fields, leaving the agent to infer meaning from names and enums.

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

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

The description clearly states the action and resource: 'Page the full business-ownership claim queue.' The verb 'page' indicates paginated listing, and the resource is specific. This distinguishes it from sibling tools like triage_admin_business_claim and list_admin_verification_cases.

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

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

The description provides a clear prerequisite: 'Requires a team/admin-agent key with review_intake.' It implies the tool is for read-only paging of the queue. However, it does not explicitly mention when not to use it or name alternatives, so it stops short of a 5.

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

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

Beyond readOnlyHint and destructiveHint annotations, it adds real value: required key type, V3 data exposure rules (current class only, no public numeric grade), and a firm non-mutation guarantee. This is rich behavioral disclosure with no annotation contradiction.

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

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

Three concise, front-loaded sentences with no filler. Each sentence contributes specific context: action, auth requirement, result semantics, and non-mutation guarantee.

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 and strong annotations, the description covers auth, result shape, and safety, which is largely complete. However, it leaves ambiguous what 'business-operations pipeline' means and does not explain key filter parameters, so a bit more context would make it fully complete.

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

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

Schema description coverage is 0% with nine parameters, so the description must compensate, but it only mentions 'Search and page' and never explains sort, cursor, status, category, source, or claim_status semantics. The description provides no parameter-level meaning.

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

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

The description clearly states it searches and pages the Loppee business-operations pipeline, with a specific verb and resource. It distinguishes from edit operations via 'never edits a business,' but does not explicitly differentiate among sibling list_admin_* tools like claims or verification cases.

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

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

The description implies usage in an admin context by requiring a team/admin-agent key and states the non-editing behavior, but it does not provide explicit when-to-use or alternative tool guidance. The context is clear only at a general level.

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 readOnlyHint/destructiveHint annotations, the description discloses sensitive details: permission requirements, short-lived signed links, raw storage references never returned, and the 'cannot mint Verified' caveat. This adds significant behavioral context.

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

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

Three sentences, each dense with information. The main purpose is front-loaded, and every sentence contributes security or behavioral context without fluff.

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

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

Given the output schema exists, the description covers key aspects: purpose, required permissions, link behavior, and a critical security property. The main omission is parameter semantics, but the tool's security-oriented context is well covered.

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

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

Schema description coverage is 0%, and the description provides no explanation for any of the four parameters (q, limit, offset, status). It merely says 'read the queue,' leaving the agent to guess what each parameter does. This is a major gap.

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

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

The description opens with 'Read the private entity/license manual-review queue,' using a specific verb and resource. It clearly distinguishes this from sibling tools like decide_admin_manual_verification_submission by focusing on read-only access to the manual-review queue.

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 states a concrete prerequisite ('Requires a team/admin-agent key whose exact allowed_actions include complete_manual_verification') and warns that reading cannot mint Verified, implying you need a different tool for approval. It doesn't explicitly name alternatives, but the context is clear.

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 and destructiveHint, but the description adds meaningful guarantees: flags never auto-hide, remove, reweight a review, or change a business class. It also discloses the queue is private and permissioned, going well beyond the structured annotations.

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

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

The description is two short sentences with the action front-loaded in the first sentence. The second sentence efficiently provides access and safety context. Every word earns its place 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?

For a read-only list tool with annotations, an output schema, and simple optional parameters, the description sufficiently covers purpose, permission, privacy, and behavioral guarantees. It does not need to explain return values because the output schema handles that, and the parameters are self-explanatory from the 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?

The input schema has three parameters (limit, offset, status) with 0% description coverage, and the description does not compensate by explaining their meaning or how status filtering works. The schema's enums and ranges help somewhat, but the description adds no parameter-level value.

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

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

The description opens with 'Read the private flag-only review-anomaly queue,' using a specific verb and resource. It clearly distinguishes itself from the sibling resolve_admin_review_anomaly by emphasizing read-only access and the flag-only scope.

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

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

The description provides clear context by stating the required key permission (moderate_reviews) and that this is the private queue for reviewing anomalies. However, it does not explicitly name alternatives like resolve_admin_review_anomaly or state when not to use it, so it stops short of full explicit guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that reading never changes class, evidence, publication, or assignment, and specifies the auth requirement (team/admin-agent key with view). This goes beyond annotations and provides useful behavioral context.

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

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

The description is a concise two-sentence structure that front-loads purpose and auth requirement, followed by a precise non-mutation guarantee. Every sentence adds value with no 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?

With an output schema present and annotations covering safety, the description adequately covers purpose and safety. However, it leaves pagination and filter semantics undocumented, which are necessary for effective use of the list functionality. Decent but not fully complete.

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

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

Schema description coverage is 0%, and the description offers no explanation of limit, cursor, filter, or search. The filter enum values ('needs_attention', 'ready', etc.) are opaque and not decoded. The agent must rely entirely on the schema without any contextual help.

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

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

The description clearly states the tool lists the server-owned verification work queue, using a specific verb and resource. This distinguishes it from siblings like get_admin_verification_case, which retrieves a single case, and from list_admin_manual_verification_submissions.

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

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

The description implies usage for viewing the back-office verification queue and notes the required auth key, but does not explicitly say when to use it versus alternatives like get_admin_verification_case. No exclusions or when-not guidance are provided.

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 indicate read-only and non-destructive behavior. The description adds valuable context beyond annotations: 'newest first', inclusion of replies, pagination mechanics, auth constraints, and the platform's limited role ('Loppee provides scoped API and MCP access only; it does not provide or host that customer-connected agent'). No contradictions exist.

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 core purpose is front-loaded, but the description contains substantial extraneous platform context: 'Under v3, a business owner connects an external agent they already use. Loppee provides scoped API and MCP access only; it does not provide or host that customer-connected agent. Access is available at no charge for now.' These sentences do not aid tool invocation and inflate length.

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

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

Given the tool's complexity, the description is highly complete: it covers pagination, scope, auth/permissions, mutually exclusive parameters, and next-step usage. The presence of an output schema means return values need not be detailed here. Even the v3 context, while verbose, explains the platform's role in access, adding to completeness.

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 60%, and the description compensates by clarifying cursor and conversation_id semantics: 'conversation_id and cursor are mutually exclusive' and 'Pass conversation_id from a webhook resource for one exact business-scoped lookup.' It also explains cursor usage in the pagination loop. However, account_id and business_id are not elaborated beyond their obvious role, so a 4 is appropriate.

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

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

The description opens with a specific verb and resource: 'List inbound customer messages for a business you manage, newest first, each with any replies already sent.' This clearly distinguishes the tool from siblings like list_support_messages and list_my_conversations by focusing on customer messages for a managed business.

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

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

The description provides explicit usage guidance: pagination traversal ('Follow pagination.next_cursor until pagination.has_more=false'), the mutual exclusivity of conversation_id and cursor, and prerequisites ('Requires allowed_actions include list_customer_messages... Requires an owner-scoped management key, explicit business scope, and the tool's permission'). It also points to a related tool: 'Use the returned interaction_id with reply_to_customer_message.'

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=true, idempotentHint=true, and destructiveHint=false, but the description goes far beyond by revealing PII handling, short-lived resume URLs, explicit owner grant requirements, and the guarantee that listing never changes statuses or verification class. This is rich behavioral context that annotations alone do not 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?

The core purpose is front-loaded and structured well, but the description contains extraneous business boilerplate ('Under v3, a business owner connects an external agent they already use... Access is available at no charge for now.') that does not aid tool invocation. While not overly long, some sentences do not earn their place, preventing a higher score.

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

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

The description covers purpose, ordering, filters, pagination, PII handling, authorization requirements, and read-only guarantees. With an output schema present, return values do not need to be described. This is fully complete for an agent to invoke the tool correctly.

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

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

The schema description coverage is 100%, so all parameters are already documented. The description summarizes filters and pagination ('Optional job_id/status filters and offset pagination (limit up to 100, default 25)') but adds no additional per-parameter semantics. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'List applications to the job postings of a business you manage, newest first.' It clearly identifies the employer side of the hiring pipeline, distinguishing it from the sibling tool list_my_job_applications (which is presumably the applicant's own view).

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

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

The description states this is the employer-side tool, implying it is not for job seekers, and details prerequisites such as 'requires allowed_actions include list_job_applications' and an owner-scoped management key. While it does not explicitly name alternative tools, the context is clear enough for an agent to decide when to use it.

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 indicate read-only and non-destructive behavior. The description adds valuable context by explicitly stating that reading missed contacts never affects verification class, ranking, or reviews, and that rows are restricted to the exact authorized business. This goes beyond the structured annotations.

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

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

The description is moderately sized and front-loaded with the core purpose, but it includes jargon such as 'v3 exposure plan' and 'owner workflow' that may obscure meaning. Some sentences repeat the access restriction theme, making it less crisp than necessary.

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

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

The description covers the primary purpose, access scope, and side-effect guarantees, which is helpful for a read-only list tool. However, the complete absence of parameter explanations and the presence of an output schema mean the description is only partially complete; users must rely on the schema for parameter meaning.

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

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

The schema description coverage is 0%, and the description does not explain any parameters (account_id, business_id, limit, offset). Since the schema itself has no descriptions, the tool description must compensate, but it provides no parameter semantics whatsoever.

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

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

The description clearly states the tool lists 'MISSED CONTACTS' for the scoped business, using the specific verb 'List' and identifying the exact resource. This distinguishes it from sibling list tools by its unique resource type and scope.

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

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

The description implies when to use the tool (to view missed contacts for the owner-authorized business), but it does not explicitly contrast it with alternative tools or state when not to use it. It provides context about scoping and security but no direct usage guidance.

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

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

Beyond the annotations (readOnly, idempotent, not destructive), the description discloses pagination behavior, auth requirements, account_id match constraint, scoped key permissions, and the guarantee that it never modifies anything. This adds meaningful context beyond structured annotations.

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

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

The description is a focused paragraph with every sentence delivering value: purpose, pagination, parameter usage, auth, and safety. It is front-loaded with the core function and then provides necessary operational details without fluff.

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

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

Given the tool's moderate complexity, the description fully covers pagination, authentication, parameter relationships, and relationship to send_message_request. An output schema exists, so the absence of return-value details is acceptable. It is sufficiently complete for an agent to invoke 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 covers 75% of parameters with descriptions. The description enriches semantics by explaining conversation_id's webhook origin, mutual exclusivity with cursor, and the requirement that account_id match the API key. It compensates for the undocumented account_id parameter, though more explicit examples could improve clarity.

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

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

The description clearly states the tool lists the calling account's own message conversations with businesses, newest first, and includes business replies. It distinguishes itself from siblings by explicitly calling itself 'the read half of send_message_request' and noting its conversational scope.

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

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

Provides explicit when-to-use guidance: reporting answers to the user, traversing pagination, and using conversation_id from a webhook for exact lookup. It also clarifies mutual exclusivity of cursor and conversation_id, and gives auth prerequisites (call get_agent_identity first, key scoping).

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 destructiveHint=false, but the description adds substantial context: it guarantees 'listing never changes an application's status and never affects any employer's verification class or recommendation order', discloses the resume_url lifetime (~5 minutes, null on signing failure), and documents key/account requirements. There is no contradiction with annotations.

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

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

The description is about 170 words, but every sentence carries meaningful information: scope, ordering, return fields, URL expiry, pagination, auth, and read-only guarantees. It is front-loaded with the main purpose and efficiently organized. It is slightly dense but appropriate for the tool's complexity.

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

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

Given the tool's complexity (4 params, auth constraints, output schema exists), the description covers all necessary context: what it returns, how to paginate, prerequisites, and side-effect guarantees. The output schema handles return structure, so no missing information is evident.

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?

All four parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds the 'newest first' ordering and a high-level summary of pagination/filtering, but does not add detail beyond what the schema already provides. It correctly respects the schema's 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?

The first sentence is 'List the calling customer account's OWN job applications, newest first' — a specific verb+resource+scope. It also explicitly frames it as 'the read half of apply_to_job', which distinguishes it from the mutation sibling and from list_job_applications (likely the admin version). This is unambiguous and fully differentiates the tool.

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

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

The description states the intended use case ('so an agent can report what happened to each application') and gives a concrete prerequisite ('call get_agent_identity first'). It also notes the account_id must match the key. The 'OWN' scope and pairing with apply_to_job imply when to use vs alternatives, and the auth requirement is an explicit condition for correct invocation.

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 (readOnlyHint, idempotentHint, destructiveHint), the description adds valuable behavioral context: returns only metadata/summaries/links, never raw CVs, full message bodies, or applicant PII, and requires a specific permission. No contradictions with annotations.

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

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

The description is three concise sentences, each adding distinct value: the main action, data exclusions, and permission requirement. No redundant wording.

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

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

The description covers purpose, scope, data exclusions, and permission requirements. With an output schema present, return values are already structured. It does not mention sorting or filter semantics, but standard list parameters are visible in the 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?

The schema has 6 parameters with 0% description coverage, and the description does not explain account_id, business_id, type, limit, offset, or unread. It only implies scope through 'scoped to,' leaving the agent to infer parameter meanings.

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

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

The description states 'List owner notifications for the business this management agent is scoped to,' providing a specific verb, resource, and scope. It also clarifies what is returned (event metadata, summaries, resource links) and what is excluded, which distinguishes it from sibling list tools.

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

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

The description gives clear context about the scoped business and the required permission ('Requires allowed_actions include list_notifications'), but it does not explicitly name alternatives or when-not-to-use conditions.

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?

Despite strong annotations (readOnlyHint, idempotentHint, destructiveHint: false), the description adds substantial behavioral context: 'Read-only: never modifies the shortlist and never affects any business's verification class or recommendation order.' It also discloses error behavior (invalid_agent_api_key, agent_account_scope_violation) and pagination semantics (up to 100, default 20, no cursor), which go beyond annotation hints.

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

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

The description is long but every sentence earns its place: scope, sort order, sibling relationship, output fields, limits, pagination, auth prerequisite, read-only guarantee, and error types. It is front-loaded with the core purpose and logically organized, with no redundant or filler content.

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

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

Given the tool's complexity (auth scoping, account-binding, read-only guarantees) and the existing rich schema/annotations/output schema, the description covers all necessary context: auth errors, ordering, default limit, no cursor, and relationship to save_business. It is fully self-sufficient for an agent to select and invoke 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%, but the description enriches parameter meaning significantly. It clarifies the limit default and max ('up to 100 entries (default 20, newest-first, no cursor)'), ties account_id to the agent key and get_agent_identity ('account_id matches the account_id argument'), and states the returned fields. This adds practical semantics beyond 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?

The description precisely states the tool's function with a specific verb and resource: 'List the calling account's OWN saved-business shortlist, newest first.' It clearly differentiates from sibling tools like save_business/unsave_business by being the read half, and from general search/recommend tools by emphasizing 'OWN saved-business shortlist.'

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 frames when to use: 'the read half of save_business, so an agent can review and report the shortlist it has built.' Also provides prerequisite guidance: 'Requires a valid scoped agent API key... call get_agent_identity first' and notes key scoping alternatives ('keys scoped to save_business may also read'). This gives clear context and exclusions beyond simply naming the tool.

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

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

Beyond the annotations (readOnlyHint, etc.), the description adds valuable behavioral details: newest-first ordering, inclusion of full message logs and statuses, strict business scope, permission prerequisites, and the v3 external-agent context. It fully discloses that this is a read-only operation and that access is not granted by exposure tier, providing transparency beyond 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?

The description is somewhat lengthy but well-structured: it leads with the core purpose, then scope, permissions, v3 context, and finally pairing advice. Each sentence adds some value, though the v3 external-agent explanation feels tangential for tool selection. Overall, it is informative without being unwieldy.

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 does not need to detail return structure, but it still explains key aspects like ordering, statuses, and scoping. It covers permission requirements and the read-only nature, making it sufficient for an agent to invoke correctly. The v3 context is extra but does not create gaps.

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

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

Only the 'limit' parameter has a schema description (33% coverage). The description helps clarify that 'business_id' refers to the business being managed and that results are scoped to that business, but it does not explain 'account_id' or 'limit' semantics. Since the schema covers little, the description partially compensates but leaves some parameter meaning implicit.

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

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

The description clearly states the tool reads Loppee support conversations for a managed business, with a specific verb ('Read') and resource ('support conversation(s)'). It distinguishes itself from siblings by specifying the owner↔Loppee-support thread, scoping to 'THIS business only', and mentioning 'pair with send_support_message'.

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

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

The description gives clear context: it is for reading support conversations and explicitly pairs with send_support_message for replies. It also notes permission requirements (allowed_actions, owner-scoped key) and that exposure tier does not grant access, which helps an agent decide when it can be used. However, it does not explicitly contrast with similar sibling tools like list_customer_messages or list_my_conversations.

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

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

The description goes far beyond the readOnlyHint annotation by detailing that results are commercially neutral unless an exposure plan is active, that sponsored ordering only affects position within the same verification class, and that the tool never alters business profiles, verification, or reputation. It also clarifies the separation of Loppee Jobs billing. This provides deep behavioral transparency.

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 front-loaded with the core purpose and then details behavioral nuances. While it is longer than necessary, each sentence adds meaningful caveats about exposure, sponsored ordering, and non-mutating guarantees. It is well-structured and not 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 read-only annotations, an output schema present, and pagination parameters covered in the schema, the description fully covers the tool's behavioral complexity, including the pay-independence model and what it does not affect. It is complete for an agent to invoke correctly.

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

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

The schema already documents all three parameters (name, limit, cursor) with clear descriptions, and the context signal indicates 100% schema coverage. The description adds no additional parameter-level detail beyond the schema, so 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.

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

The description opens with 'Universal, pay-independent business-name lookup', which clearly identifies the verb (lookup) and resource (business name). It distinguishes itself from siblings like search_businesses by emphasizing exact-name lookup and relevance-authoritative matching, making the purpose unambiguous and specific.

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

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

The description provides clear context about what the tool does (pay-independent name lookup) but does not explicitly state when to use it versus alternatives like search_businesses. No exclusions or alternative tool references are mentioned, so usage 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.

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

The description explicitly states 'operation=delete removes the deal,' which is a destructive action, but the annotations set destructiveHint to false. This is a direct contradiction. Additionally, the description does mention non-idempotent transitions ('Not idempotent for create/delete/publish transitions'), but the contradiction overshadows this.

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 front-loaded with the purpose and operation details, but it becomes verbose in the middle with platform business model information ('Under v3, a business owner connects an external agent... Loppee provides scoped API and MCP access only... Access is available at no charge for now'). This goes beyond what is needed for tool invocation and could be trimmed.

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

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

Given the tool's complexity (11 params, 5 operations, permissions), the description covers operations, state transitions, idempotency, and prerequisites well. It also clarifies that the tool does not affect verification class or recommendation order. The existence of an output schema means return values need not be described, so the coverage is strong despite some missing edge-case details.

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

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

With schema coverage at 55%, the description adds value by explaining operation semantics ('operation=create makes a draft, operation=publish takes a draft live'), the conditional requirement for deal_id ('Required for update/publish/unpublish/delete'), and the meaning of account_id and business_id. It also clarifies date behavior (null/absent = live immediately or no expiry) even though the schema partially covers that.

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

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

The description opens with a specific verb and resource: 'Create, edit, publish, unpublish, or delete a deal/coupon for a business you manage.' It clearly distinguishes this management tool from customer-facing siblings like redeem_coupon and validate_coupon by focusing on the full lifecycle of deal records.

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

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

The description provides clear prerequisites and context: 'Requires allowed_actions include manage_deals,' 'Requires an owner-scoped management key, explicit business scope,' and 'Call get_agent_identity first.' While it does not explicitly name alternative tools, it implies usage for managing deals rather than redeeming or validating them, which is enough given the sibling context.

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 richly details behavioral traits beyond annotations: create always makes a draft, publish requires verified/published business and may return a Stripe checkout for a human to pay (never completed by the tool), update overwrites only supplied fields, delete is idempotent for missing postings, and billing never affects rankings. It also discloses auth/scope requirements and the 'not idempotent' caveat.

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 long but every sentence earns its place, covering operations, billing, auth, and prerequisites. It is front-loaded with the core verb list and logically organized; no redundant 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 complex 27-parameter tool with an output schema, the description covers all major workflows, side effects, prerequisites, billing nuances, and access requirements. It leaves little ambiguity about when and how to invoke the tool correctly.

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

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

Schema coverage is only 44%, but the description compensates by explaining the critical operation parameter's semantics (draft, publish checkout, pause/close/delete), update's merge behavior, and create defaults for city/state/category. It does not enumerate all 27 parameters, but it adds meaningful value on the most complex ones.

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

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

The description opens with a specific verb list ('Create, edit, publish, pause, close, or delete') and identifies the resource ('a job posting for a business you manage'). It also distinguishes from siblings by noting it mirrors manage_business_deal, making its scope clear.

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

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

The description provides clear context on when to use this tool (owner managing job postings) and prerequisites ('Call get_agent_identity first', requires allowed_actions, owner-scoped key). It does not explicitly contrast with alternatives like apply_to_job, but the scope is self-evident and it warns what the tool does not do (billing only activates, never ranks jobs).

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

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

The description discloses that the operation requires permission (allowed_actions) and is scoped to the agent's business, adding context not present in the annotations (readOnlyHint false, idempotentHint true). It does not contradict the annotations and clarifies the mutating nature of the action.

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

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

The description is two sentences, front-loaded with the action and scope, with no unnecessary words. The second sentence adds a critical permission requirement efficiently.

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?

This is a low-complexity tool with an output schema and good annotations. The description covers the action, scope, and a required permission, making it sufficiently complete for an agent to select and invoke the tool correctly. There is no need to detail return values because 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?

The schema has 0% description coverage, but the parameter names (account_id, business_id, notification_id) are self-explanatory. The description's overall purpose ('mark one owner notification as read') implies the role of notification_id, but it doesn't explicitly elaborate on each parameter, leaving some interpretation to the agent.

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

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

The description uses the specific verb 'Mark' with a clearly defined resource ('owner notification') and scoping ('for the business this management agent is scoped to'). It clearly distinguishes from list_notifications, which lists notifications rather than mutating one.

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 specifies the context for use—marking a single owner notification as read within the agent's business scope—and states a required condition (allowed_actions must include mark_notification_read). It doesn't explicitly contrast with alternatives, but no sibling tool performs the same action.

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

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

The description goes far beyond annotations by detailing fallback rules (at most one unrated unclaimed Registry row, only when higher-authority pools are empty), sponsored exposure confidentiality, the 25% Free exposure floor, and the neutrality of city/ZIP/provider IP. It also clarifies that Loppee Jobs is a separate paid product, eliminating cross-product misconceptions. This is exemplary 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.

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

The description is a single dense block of many sentences, lacking bullets, sections, or subheadings. While every sentence carries meaningful rules, the wall-of-text format makes it difficult to parse quickly. Front-loading is present but quickly buried under exhaustive edge-case details.

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

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

For a tool with 11 parameters, an output schema, and complex behavioral rules, the description is exceptionally complete. It covers sponsored ordering, exposure floors, fallback rules, location authority tiers, and the distinction between name lookup and category discovery. The output schema handles return values, so the description appropriately focuses on operational constraints.

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

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

The schema already describes all 11 parameters with 100% coverage, so the baseline is 3. The description adds cross-parameter semantics, such as how city/state/ZIP/radius interact with location authority and how location_selection/saved_location_ref/location_handoff_id determine reach. This adds meaning beyond individual schema descriptions.

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

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

The description opens with a specific verb and resource: 'Return recommendations in explicit Verified, Listed, reviewed_registry, and fallback_registry sections.' This clearly distinguishes it from search/lookup tools by describing the tiered output structure. It also explains the two primary modes (category vs. name), covering the tool's full scope.

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

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

The description gives explicit context on when local category recommendations are allowed (current precise location, handoff, or saved_exact Home) and that coarse context only supports business-name disambiguation. However, it does not explicitly name alternative tools like search_businesses or lookup_business, missing an opportunity to direct agents to the right sibling.

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 (which only indicate non-read-only, idempotent, non-destructive), the description discloses critical behaviors: it never charges, creates a pending redemption that auto-releases on expiration, counts against redemption limits while pending, is idempotent, refuses competing checkouts, and clearly states that it only changes price. This goes far beyond what annotations provide, with no contradictions.

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 long and dense, but every sentence adds necessary context (idempotency, failure modes, side effects, prerequisites). It front-loads the core purpose and then systematically covers edge cases. While it could be broken into bullet points for easier parsing, the density is justified given the tool's complexity. It is not merely padded.

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

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

Given the tool's complexity, the presence of an output schema, and rich input schema, the description is complete: it covers the exact return values (url, price breakdown, redemption_id), all machine-readable error codes, the pending-redemption lifecycle, and the scope of effects. No important context is missing, making it highly actionable for an agent.

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

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

The input schema already provides 100% coverage with descriptions for all parameters, including enums and explanations of 'tier' and 'period'. The description adds minimal extra parameter semantics, mostly reinforcing the overall behavior rather than clarifying individual parameters. It stays at the baseline since 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?

The description opens with a specific verb and resource: 'Redeem a Loppee-issued subscription coupon for a business you manage.' It goes on to clearly distinguish itself from the sibling validate_coupon by explaining that it validates then creates a Stripe Checkout session. This provides a precise, non-tautological purpose that is easily distinguished from all sibling tools.

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

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

The description explicitly states when to use and when not to use the tool: 'do not call this speculatively — use validate_coupon to check a code' and 'call get_agent_identity first.' It also outlines prerequisites (matching account_id/business_id, allowed_actions, enabled online billing) and lists the exact error conditions, giving an agent clear decision criteria.

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

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

The description adds substantial context beyond the annotations: idempotency behavior (client_message_id reuse with different content rejected), permission requirements (owner-scoped key, explicit business scope, allowed_actions), and storage/attribution effects (attributed to agent, no verification class change). This is far more than the idempotentHint and readOnlyHint flags 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?

The description is longer than average but every sentence contributes operational or safety-critical information (idempotency, permissions, attribution). It is front-loaded with the core action and then layers relevant details. Slightly verbose but not wasteful.

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

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

Given the tool has 5 required parameters, an output schema, and annotations, the description covers all critical aspects: idempotency, permissions, prerequisites, and side effects. It is complete enough for an agent to invoke the tool correctly without needing to infer hidden behavior.

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 only 20% (only interaction_id has a description). The description explains interaction_id (from list_customer_messages) and client_message_id (idempotency and rejection), and implies body is the reply text. However, account_id and business_id are not explicitly described, leaving a gap in a 5-param tool. It adds meaning but does not fully compensate for low schema 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?

The description opens with 'Post a reply to an inbound customer message on behalf of a business you manage,' which is a specific verb+resource combination that clearly distinguishes this from siblings like send_message_request or respond_to_review. It also names the source of interaction_id (list_customer_messages), reinforcing the specific intent.

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

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

It clearly states when to use the tool (replying to an inbound customer message) and provides a prerequisite (get interaction_id from list_customer_messages). It does not explicitly exclude alternatives like send_message_request, but the context is strong enough to infer the appropriate scenario.

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?

Even though annotations include readOnlyHint=false, destructiveHint=false, openWorldHint=true, the description goes far beyond them. It explicitly discloses that reporting NEVER removes the review, moderation is human and reactive, and a review is removed only for a recorded policy violation. It also states the side-effect-free nature (no change to verification, weighting, or ranking) and access requirements. This is rich behavioral context above the annotations, with no contradiction.

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

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

The description is informative but quite long, with multiple sentences covering various rules and context. While most sentences add value, some tangential details (e.g., 'Under v3, a business owner connects an external agent...', 'Access is available at no charge for now') do not directly help the agent select or invoke the tool. It is not as concise as it could be; a tighter structure would be better.

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

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

The description covers prerequisites, side effects, eligibility constraints, error conditions (e.g., review_report_not_negative, review_report_already_open, review_report_limit_reached, review_not_found), and explicitly directs the agent to get_agent_identity first. Combined with the rich input schema and presence of an output schema, the tool is fully contextualized for correct invocation.

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

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

The input schema already provides 100% parameter coverage with descriptions. The description adds extra semantic context, such as 'The review is negative' is not a valid reason_category, and explains constraints on which reviews can be reported. This exceeds the baseline but does not deeply elaborate each parameter individually, so a 4 is appropriate.

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

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

The description opens with a specific verb and resource: 'Report a customer review of a business you manage into Loppee's moderation queue for a claimed policy violation.' It clearly lists the policy categories and explicitly differentiates from the sibling tool 'respond_to_review' by advising against suppressing honest criticism. The purpose is unambiguous and distinguishable.

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

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

The description provides explicit usage guidance: use it only for policy violations, never for negative reviews; use respond_to_review for public responses. It also states prerequisite conditions (call get_agent_identity first, require allowed_actions, owner-scoped key) and eligibility rules (only ratings 3 and below, only one open report, max 3 lifetime reports). These conditions and exclusions are clearly actionable.

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 (destructiveHint=true), the description adds critical context: it requires a specific permission key, modifies 'only the flag,' and explicitly lists what it does not do. This clarifies the exact blast radius of a destructive operation, which is highly valuable and goes beyond the structured annotation hints.

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

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

The description is two sentences long, front-loaded with the core purpose, and every sentence adds value. There is no redundancy with the schema or annotations, making it appropriately concise and well structured.

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 destructive, permission-gated tool with four required parameters and an output schema, the description fully covers the essential context: what it does, its side effects, its permissions, and its boundaries. Since an output schema exists, omitting return details is appropriate. The description is complete for this complexity level.

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

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

With 0% schema description coverage, the description partially compensates by mentioning 'recorded reason' (resolution_note) and 'exact confirmation' (confirm). However, it does not clarify the relationship between status and confirm (e.g., that confirm must match the chosen status), nor does it add meaning for flag_id. The schema's enums and UUID format provide some structure, but the description leaves gaps in parameter semantics.

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 phrase 'Resolve or ignore one anomaly flag' that clearly identifies the action and resource, including the singular scope ('one'). It also distinguishes itself from review-level mutations by stating it 'cannot hide/remove the review, change review weight, or change a business class,' which differentiates it from siblings like report_review or submit_review_for_moderation.

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 provides a clear prerequisite ('Requires a team/admin-agent key with moderate_reviews') and explicit exclusions (does not affect the underlying review). However, it does not name alternative tools or explicitly state when to prefer this over list_admin_review_anomalies or other review-related tools, leaving some usage inference to the agent.

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 annotations (idempotentHint, destructiveHint), the description details crucial behaviors: the response is public and attributed to the agent, it never changes verification class, review authority, rating, or weighting, and it returns specific error cases. It also explains that exposure tier does not grant/remove access, which is valuable context not in annotations.

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

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

The description is a long, single-paragraph wall of text with extraneous business context ('Under v3, a business owner connects an external agent...', 'Loppee provides scoped API and MCP access only...', 'Access is available at no charge for now.') that does not aid tool selection or invocation. Key points are buried, reducing scannability.

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?

Despite being verbose, the description is thorough: it covers auth requirements, idempotency, side-effect non-changes, error returns, and the proper call sequence. Given the output schema exists and annotations are present, the description leaves no critical operational gap.

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

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

Schema description coverage is 100%, so the parameters are well-documented in the schema. The tool description adds little beyond that; it only ties account_id to get_agent_identity and mentions body limits already in the schema. This meets the baseline for full schema coverage but does not exceed it.

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

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

The description opens with a specific verb+resource: 'Publish the business's ONE public response to a customer review.' It distinguishes from siblings like report_review and reply_to_customer_message by emphasizing the public, one-per-review nature and by clarifying it 'only adds the business's side of the story.'

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

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

The description gives explicit prerequisites: requires allowed_actions contain respond_to_review, an owner-scoped management key, explicit business scope, and tool permission. It also instructs 'Call get_agent_identity first' and clarifies that repeating the call edits the existing response, preventing misuse.

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 destructiveHint=true, but the description goes far beyond: irreversibility, self-only authorization, live DB check meaning no cache window, audit logging before disable, confirm_required without confirmation, env_key_not_revocable for operator keys, and the fact that revocation is effective on the next request. There is no contradiction between description and annotations.

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

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

The description is a single dense paragraph but remains front-loaded with the core action in the first sentence. Subsequent sentences deliver high-value warnings and edge cases. It is longer than typical but appropriately so for a destructive, irreversible operation with multiple behavioral caveats.

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

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

For a tool with low parameter count but high stakes, this description covers the complete operational context: what happens on success, the required confirmation, the no-cache guarantee, audit logging, revocation limitations, operator-key exception, and the alternative tool for identity confirmation. The output schema exists, so the description focuses on using the tool correctly rather than return values, which is appropriate.

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

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

The one required parameter, confirm, is a bare boolean in the schema with 0% coverage. The description fully compensates by explaining its semantic role: 'Requires confirm:true — without it the tool returns confirm_required and changes nothing.' This provides actionable meaning far beyond the schema type.

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

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

The description opens with a specific, unambiguous action: 'Immediately and irreversibly revoke the API key THIS call authenticates with.' It clearly identifies the resource (the calling key itself), the scope (self-only, never another key), and the effect (removes access). It also distinguishes itself from related tools like get_agent_identity and minting/issuing operations, making its purpose unmistakable.

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

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

The description gives explicit when-to-use context (key exposed, integration retired, user asked to disconnect), clear what-it-does-not-do (cannot revoke other keys, cannot mint new keys), and a direct alternative/prerequisite: 'Call get_agent_identity first if you need to confirm which account and label this key belongs to.' It also specifies the required confirm flag behavior and two possible error/return states.

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, the description adds crucial behavioral details: it does not contact the business, it is idempotent (same business twice is a no-op), it does not affect verification or reputation scores, and it returns specific machine-readable auth errors. These are significant disclosures that the annotations do not fully capture.

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

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

The description is compact and front-loaded: the first sentence captures the essence, and subsequent sentences provide necessary caveats (idempotency, side effects, auth errors) without redundancy. Every sentence adds value and the structure is logical.

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 documentation is unnecessary. The description covers purpose, auth prerequisites, idempotency, non-interference with business metrics, and error conditions, giving a well-rounded picture. It could mention validation or other error cases, but the existing coverage is strong for an 8-parameter mutation tool.

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

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

The schema has 0% description coverage, so the description must compensate for parameter meanings. It does explain that account_id must match the agent key, but it does not elaborate on business_name, business_source, city, state, notes, or category. Some parameters are self-explanatory from the tool's purpose, but the description does not fully cover all 8 parameters.

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

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

The description opens with a specific verb ('Attach') and resource ('a published business or directory listing'), and clarifies it is a shortlist action that does not contact the business. It clearly distinguishes from sibling tools like list_saved_businesses and unsave_business, making the tool's place in the workflow explicit.

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

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

The description provides clear usage context: it is for attaching businesses to a shortlist workflow, and it explicitly names related tools for reading and pruning. It also states the prerequisite of calling get_agent_identity first to confirm API key scope. However, it does not explicitly state when not to use this tool (e.g., if the business is not published), so it falls just short of a 5.

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

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

Discloses extensive behavioral rules beyond the readOnly/destructive annotations: location authority gates category/recommendation reach, neutral context records no impressions, exposure-plan payment changes Sponsored ordering but never business-profile publication or verification, and Loppee Jobs billing is separate. No contradiction with annotations.

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

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

The description is a single dense paragraph with significant repetition (e.g., city/ZIP being neutral context and unable to enable local category reach is restated many times). While the detail is valuable, it lacks structural organization and could be made more concise with bullets or paragraph breaks.

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

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

Given 13 parameters, complex location-gating rules, and commercial neutrality requirements, the description is exceptionally complete. It covers prerequisites, persona restrictions, location selection rules, and side effects like impressions and Sponsored exposure. The output schema handles return-value documentation.

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 every parameter already has a detailed description. The tool-level description adds high-level conceptual context (closed taxonomy vs name lookup, location authority model) but does not elaborate on individual parameters beyond the schema's own semantics. The baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Search Loppee's closed taxonomy or use universal business-name lookup.' It clearly separates two search modes and, with the sibling search_category present, distinguishes this tool by highlighting taxonomy routing and universal name lookup.

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

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

The description gives explicit usage workflow: first call get_location_options and ask the customer a scripted question. It states when to use current/saved locations, when only saved_exact authorizes local category discovery, and that provided city/ZIP are for name disambiguation only. It also excludes other personas from local discovery.

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 read-only/harmless, but the description adds extensive behavioral detail: neutral context records no impressions, sponsored placement requires precise location, exposure-plan payment never affects profiles/verification, and location handoff is used privately. These go well beyond the annotations.

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

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

The description is a single dense paragraph that repeats the same core constraints multiple times, such as 'neutral area context for business-name disambiguation only' and the precise-location requirement. While content is valuable, the lack of structure and redundancy make it harder to parse than necessary.

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

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

Given the complexity (10 parameters, several location modes, commercial influence), the description is comprehensive. It covers location authority types, persona restrictions, commercial neutrality, Sponsored placement, exposure-plan effects, and privacy. An output schema exists, so return-value details are not needed.

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 detailed per-parameter descriptions, so baseline is 3. The description adds cross-parameter meaning by categorizing parameters into authoritative location (current, handoff, saved_exact) vs neutral context (zip, city, state, radius, coarse saved) and explaining how location_selection and saved_location_ref interact.

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

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

The description clearly identifies the tool as local category discovery, contrasting it with business-name disambiguation ('Exact and genuine-prefix business-name lookup remains universal'). It specifies the required scope: current precise location or saved_exact Home for actual category results, while city/ZIP/coarse Home are only context.

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

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

Provides explicit when-to-use/when-not-to-use guidance. It states that city/state, ZIP, provider IP, saved_coarse, and caller-supplied coordinates return no local category results and are for business-name disambiguation only. It also notes that other agent personas cannot access customer location authority and implies alternative tools via the business-name lookup exemption.

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