Loppee

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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=true. The description adds significant behavioral context: requires a specific agent key, resume storage in a private bucket, and retrieval via signed URLs. 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 four sentences, front-loaded with the purpose, and each sentence adds value. There is no 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?

For a tool with 4 parameters (including a nested object) and no output schema, the description covers purpose, authentication, cost, resume format and storage. It lacks details on success behavior, errors, and idempotency implications, but overall is fairly 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%, so the description must compensate. It clarifies that the resume must be a base64 PDF, DOC, or DOCX file and that account_id must match the agent key's account_id. However, it does not explain job_id, cover_note, or the resume object fields like file_name and size_bytes.

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 on behalf of the calling customer account,' specifying the verb, resource, and context. It distinguishes from siblings like list_job_applications or withdraw_job_application by focusing on the submission action.

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 and the required authentication ('requires a customer personal agent key whose account_id matches...'). It also notes 'The seeker is never charged,' providing cost context. However, it does not explicitly mention when not to use or directly compare to 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?

Description goes beyond annotations by disclosing idempotency details (returns available=false on no-op), fallback to IP-derived default, and authentication constraints. No contradiction with annotations (readOnlyHint=false, idempotentHint=true).

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

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

Three sentences, front-loaded with the primary action. Each sentence provides necessary information without waste. 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?

No output schema, but description mentions return value 'available=false'. It could more fully describe the response structure (e.g., full return object), but given simplicity and idempotency, it is adequate for agent 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 coverage is 100% with only account_id. Description adds context: 'confirm with get_agent_identity' and explains that the key's account_id must match the argument. This adds meaning beyond the raw 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?

Description clearly states 'Remove the calling customer account's saved home location' with specific verb and resource. It distinguishes from sibling tools like set_my_location and get_my_location by focusing on removal.

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?

Description explains idempotency, fallback behavior after clearing, and authentication requirement. It implicitly indicates when to use (to remove location) but does not explicitly state when not to use or list 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 discloses the neutral ranking approach (commercial_influence:"none"), ordering criteria (safe_to_recommend, trust_score, confidence, name), and handling of unresolved IDs. Annotations confirm readonly and open-world behavior, 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 concise yet comprehensive, structured with a clear purpose, usage instructions, and detailed output fields. Every sentence adds value without redundancy.

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

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

The description fully explains the tool's behavior, input constraints, output content, and differentiation from a sibling tool. No output schema is needed as the description covers the return fields.

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

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

Only one parameter (business_ids) is present, with 100% schema coverage. The description does not add extra semantics beyond what the schema already provides, so the 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 clearly states that the tool provides a normalized side-by-side comparison of 2 or more businesses, allowing ranking without individual calls. It explicitly differentiates from recommend_businesses by highlighting its neutral, unbiased nature.

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 advises to use this tool when an unbiased quality ranking of a known candidate set is needed, and contrasts it with recommend_businesses. It also notes that unresolved IDs are not ranked.

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 it requires a published business and returns an error for invalid records, and lists the returned fields. 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 three sentences, with the first sentence giving the core purpose, the second listing fields, and the third stating error conditions. Every sentence is necessary and front-loaded.

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 low complexity (single parameter, no output schema) the description covers purpose, usage, return fields, and error cases. It is complete enough for an agent to use 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% for business_id with description. The description adds the constraint that the business must be published, which is not in the schema description. This adds value 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 the tool returns the structured 'why' behind a recommend/not-recommend decision for one published business. It distinguishes from siblings like get_trust_card (which returns the full Trust Card) by emphasizing a single-call lightweight justification.

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 explains it can be used to justify a pick without re-fetching the whole Trust Card, and explicitly notes it returns an error for unpublished, blocked, or unknown records. While it doesn't name sibling tools explicitly, 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=true and destructiveHint=false. The description adds specific details about what is returned (contract, endpoints, policy rules, MCP tools), providing moderate additional context 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?

Single sentence that is concise and front-loaded. No extraneous information; every word adds value.

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

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

Given no parameters, no output schema, and a clear listing of returned data categories, the description is fully complete for the tool's purpose.

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

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

The input schema has no parameters, so schema description coverage is effectively 100%. Description does not need to add parameter information; baseline 4 for zero 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 clearly states the tool returns the Loppee agent contract, endpoints, policy rules, and available MCP tools. It uses a specific verb 'Return' and specifies the resource, distinguishing it from sibling tools like get_agent_identity.

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

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

No guidance on when to use this tool versus alternatives. The description does not mention when it is appropriate or inappropriate to invoke it, nor does it reference sibling tools for comparison.

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 provide readOnlyHint and destructiveHint. The description adds context about authentication (X-LOPPEE-API-Key or Authorization: Bearer) and error behavior on missing/revoked keys, which is valuable beyond 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?

Three well-structured sentences with no redundant information. Critical details (return values, usage order, prerequisites, error handling) are front-loaded.

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

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

Given no parameters, no output schema, and clear annotations, the description fully covers what the tool does, when to use it, and its behavior. No 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?

No parameters exist; schema coverage is 100%. Baseline score of 4 applies as per guidelines 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 identifies the calling agent from its API key, returning account_id, label, and allowed_actions. It distinguishes from sibling write tools by emphasizing its role in permission discovery before write operations.

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

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

Explicitly instructs to call this first to confirm key validity and discover permissions before writing. Also specifies authentication method and error condition for missing/revoked keys.

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 non-destructive, read-only behavior. The description adds valuable context: reviews are display-only, never affect trust score or ranking, and reviewer names are masked. 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?

Description is detailed but front-loaded with key purpose and pagination details. Every sentence adds value, though slightly verbose with parentheticals; could be tightened without losing substance.

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?

No output schema is provided, but the description fully explains return fields (pagination, summary.rating_counts), errors, and behavioral invariants. Complete for a read-only paginated 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?

Input schema covers 100% of parameters with descriptions. The description adds default values, range details, pagination mechanics (has_more/next_page), and error names, enriching understanding beyond 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?

Clearly states it reads published customer reviews with pagination and star-rating filters. Distinguishes itself from 'get_trust_card' which only embeds a slice, making its purpose unique among 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?

Explicitly tells when to use the full reviews tool vs. the Trust Card, describes pagination controls, and lists error conditions (not_found, invalid_rating_filter). Provides clear guidance on 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?

The description adds significant value beyond annotations: it clarifies the location is used automatically by search/recommend tools, ensures no side effects on business scores, specifies the authentication prerequisite, and documents the return behavior when no location is saved. 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 concise and front-loaded with the core purpose, followed by behavioral and prerequisite details in three clear sentences. No unnecessary information; every sentence adds value.

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 output schema, the description adequately covers the return value (available=false) and all key aspects: purpose, side effects, prerequisites, and role in the ecosystem. It is complete for a simple read-only tool with one parameter.

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 (100% coverage). The description restates the same information about matching the personal-agent key, adding no new semantics beyond what the schema provides. 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 title and description clearly state the tool reads the customer's saved home location, specifying it is a ZIP or precise point with label. It distinguishes itself as the persistent discovery anchor used by search/recommend tools, differentiating it from siblings like set_my_location or clear_my_location.

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 explains the tool is a discovery anchor and never affects trust scores, rankings, or reviews, and notes the prerequisite of a valid personal-agent key with matching account_id, even referencing get_agent_identity. It does not explicitly state when not to use it or compare to 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, and description adds valuable context: pricing never affects trust_score, safe_to_recommend, etc. This extra behavioral detail goes beyond 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?

Description is reasonably concise with two sentences and front-loaded. Slightly wordy but not excessive; all information is relevant.

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 no output schema, description thoroughly explains what is returned (prices, features, add-ons, promotions) and clarifies what is not affected. Complete for a read-only 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?

No parameters exist, schema coverage is 100%. Baseline 4 for zero parameters; description adds no param info but is not 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?

Description clearly states the tool returns Loppee's published pricing plans with specific details (prices, feature bullets, branch add-ons, promotions). This is a unique resource with no sibling tools covering pricing, so it is well-differentiated.

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?

Description implicitly indicates usage (to get public pricing info) and mentions it's the same as the /pricing page. No explicit alternatives or when-not-to-use, but given no sibling for pricing, this is sufficient.

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 value by detailing that it returns an error for certain conditions, listing the contents (trust score, evidence breakdown, etc.), and specifying that it is for a published business. This goes beyond 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 with no wasted words. The first sentence states purpose and usage, the second details content and error behavior. 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?

Given 2 parameters, no output schema, and sibling tools that could overlap, the description covers the return content, error cases, and usage context. It lacks details on pagination or format, but for a fetch tool it is adequate.

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 descriptions for business_id and domain_key. The description mentions both parameters and the need for one, but does not add significant meaning beyond what the schema provides. 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 clearly states the tool fetches a Trust Card for a business by business_id or domain_key, listing specific included fields (trust score, evidence breakdown, etc.). It distinguishes this from sibling tools like 'explain_recommendation' or 'lookup_business' by emphasizing verification and citation for a specific 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?

Explicit guidance: 'use this to verify, justify, or cite a specific business before acting.' Also notes errors for unpublished/blocked/unknown records. While it doesn't explicitly state when not to use or name alternatives, the context is clear given sibling tools.

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 readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral details: messages include replies, ordering is newest-first, and rate limit behavior ('management_rate_limited'). This goes 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 extremely concise, consisting of two sentences that efficiently convey purpose, usage requirements, and output usage. Every sentence adds value without redundancy.

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

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

Given no output schema, the description explains what is returned (messages with replies), ordering, prerequisites, rate limits, and how to use the output (interaction_id for reply). This is complete context for a list tool with rich annotations.

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

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

Schema description coverage is 33% (only 'limit' has a description). The description does not add semantic meaning to 'account_id' or 'business_id' beyond the schema's minLength constraints. For a tool with low coverage, the description should compensate but does not.

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 ('List inbound customer messages'), the resource ('messages for a business you manage'), and ordering ('newest first'). It also distinguishes itself from sibling tools like 'reply_to_customer_message' by noting the returned interaction_id is used with that 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 provides explicit prerequisites ('Requires a scoped management key with allowed_actions list_customer_messages'), rate limit information, and hints at downstream use ('Use the returned interaction_id with reply_to_customer_message'). However, it does not explicitly contrast with other list tools like 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?

Adds significant context beyond annotations: PII notice, resume_url expiry, owner grant requirement, audit logging, rate limiting, and read-only assurance. 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?

Front-loaded with purpose. Information is dense but some redundancy (e.g., rate limit mentioned twice). Could be slightly tighter.

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?

Covers purpose, usage, behavioral details, parameters, and constraints. No output schema, but description explains returned fields. Comprehensive for a list 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?

Schema description coverage is 100%, so baseline 3. Description mentions optional filters and pagination, but these are already in schema. No additional semantic 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 states it lists applications to job postings of a business you manage, newest first, and specifies the employer side. This clearly distinguishes from siblings like list_my_job_applications.

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

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

Explicit guidance on when to use (employer side), required key scoping, rate limiting, and filters. No explicit when-not-to-use, but the employer-side focus implies contrast with applicant-side tools.

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

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

Adds significant behavioral details beyond annotations: explains read-only nature and that it does not affect trust scores/ranking/reviews. Also describes plan-dependent data visibility. 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?

Front-loads the core purpose, then adds necessary details. While slightly long, every sentence adds value. Could be more concise by removing redundancy (e.g., reads 'reaches' in one spot).

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?

Describes output behavior for paid vs free plans, but omits pagination details (limit/offset not explained). No output schema, so more description of return values would help. Lacks ordering or sorting info.

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 has 0% description coverage, and the description does not explain any of the four parameters (account_id, business_id, limit, offset). This leaves agents guessing about required vs optional and their 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?

Clearly states it lists missed contacts for the scoped business. The title and description align, and the verb 'list' with specific resource 'missed contacts' differentiates it from sibling tools like list_customer_messages or list_my_conversations.

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 context on when to use (captured blocked attempts), plan differences (paid vs free), and requirements (scoped management key). However, it does not explicitly list alternatives or when not to use this tool.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description reinforces these and adds details about authorization: requiring a scoped agent API key whose account_id matches, and that keys for send_message_request may also read. This goes beyond the annotations by explaining permission nuances. 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 three concise sentences: each serves a distinct purpose (purpose, prerequisites, read-only nature). It is front-loaded with the key functionality and includes no extraneous information. Every sentence adds value.

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, the description covers the main aspects: what it returns (conversations with replies, newest first), authorization requirements, and read-only behavior. It does not detail pagination or full response format, but the context signals (no output schema) and annotations (openWorldHint) make this acceptable. It is complete enough for an agent to use 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 50%: limit is described, account_id is not. The description adds meaning for account_id by explaining it must match the API key's account_id and identifies the customer account whose conversations are listed. This compensates for the schema gap. The limit parameter is already described in schema, so no additional info 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 clearly states it lists the calling customer account's own conversations with businesses, newest first, including replies. It also positions itself as the 'read half' of send_message_request, distinguishing it from sibling tools like send_message_request or list_customer_messages.

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

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

The description provides clear context for use: as the read counterpart to send_message_request, for reporting answers back to users. It specifies prerequisites (valid scoped agent API key with matching account_id, and calling get_agent_identity first) and notes that keys scoped to send_message_request may also read. It does not explicitly list when not to use, but the context is sufficient.

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 critical behavior: listing never changes application status, never affects employer trust score or ranking, and resume_url is short-lived (5 minutes) and becomes null if signing fails. This provides rich behavioral context consistent with the safe read-only nature.

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 fairly dense but every sentence serves a purpose—explaining scope, output fields, pagination, auth, and behavior. It could be slightly more compact, but the structure is logical and front-loaded with the core purpose.

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

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

Given the complexity (4 params, no output schema), the description compensates well by detailing returned data: employer-set status, job/employer summary, cover note, and resume_url with TTL and null condition. It also covers auth and pagination. No critical gaps remain for an agent to use the tool effectively.

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 4 parameters are described in the schema (100% coverage), so the description's added value is moderate. It clarifies the account_id must match the customer personal agent key, enumerates the status filter values again, and confirms default limit is 20 with maximum 50. This adds meaningful context beyond the schema, especially the auth requirement.

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 customer account's own job applications, newest first, and frames it as the read half of apply_to_job. It specifies scope (OWN), ordering, and distinguishes from the sibling list_job_applications tool by mentioning the customer-specific 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 provides explicit when-to-use guidance: to report on applications. It includes prerequisites (call get_agent_identity first), explains key scope requirements, and notes that keys minted before this tool existed may still work with apply_to_job scope. It also advises re-listing to refresh the signed resume URL, offering clear usage instructions.

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, idempotent, non-destructive behavior. The description adds valuable context about data privacy: it 'never includes raw CVs, full message bodies, or applicant PII' and specifies that it returns 'event metadata, summaries, and resource links only'. 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 extremely concise at two sentences, front-loading the core purpose in the first sentence. Every sentence provides essential information without redundancy.

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

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

Given the tool has 6 parameters including filters like type, pagination (limit/offset), and unread flag, the description lacks guidance on how to use these filters effectively. It also does not describe the return format beyond vague mentions of metadata and summaries, and there is no output schema. For a list tool, this is insufficient.

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%, meaning the schema provides no parameter descriptions. The tool description does not explain the meaning or usage of any of the six parameters (type, limit, offset, unread, account_id, business_id), leaving the agent to infer from parameter names 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 clearly states the verb 'List', the resource 'owner notifications', and the scope 'for the business this management agent is scoped to'. It differentiates from sibling list tools by specifying 'owner notifications' rather than customer messages or job applications.

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 mentions a required authorization ('Requires allowed_actions include list_notifications'), which is a prerequisite. However, it does not explicitly state when to use this tool over alternatives or when not 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?

The description declares read-only behavior, no modification of shortlist or business trust scores, and mentions auth error returns. This aligns with annotations (readOnlyHint=true, destructiveHint=false) and adds specific behavioral details like sorting order, limit, and no cursor.

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 paragraph with essential information front-loaded. It covers purpose, usage, parameters, behavior, and error responses without redundancy. Some sentences could be combined for tighter prose, but overall it is efficient.

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

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

Given no output schema, the description enumerates return fields (business_id, name, source, etc.), limits, sorting, and auth errors. For a simple list tool with 2 parameters, this provides full contextual completeness for an agent to understand what to expect.

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% for both parameters (limit and account_id). The description adds context (newest-first, no cursor, default 20) but does not significantly enhance meaning beyond the schema; baseline score 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 explicitly states the tool lists the calling account's own saved-business shortlist, newest first, and positions it as the read half of save_business. It clearly distinguishes from sibling tools like save_business and unsave_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 explains when to use the tool (to review/report the built shortlist) and specifies prerequisites: a valid scoped agent API key with matching account_id, and recommends calling get_agent_identity first. It does not explicitly state when not to use, but context makes it clear this is for read-only access.

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 read-only nature, rate-limiting (management_rate_limited), scoping, ordering, statuses, and plan tier compatibility. Adds significant behavioral context beyond annotations (e.g., works on Free plan, hourly allowance).

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?

Concise, well-structured with front-loaded purpose. Each sentence adds value without redundancy. Approximately 4 sentences covering all key aspects.

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?

Comprehensive coverage of purpose, scope, requirements, rate limits, read-only nature, and pairing. Sufficient for agent decision-making given annotations and schema, despite low parameter description coverage.

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?

Input schema has 33% description coverage (only limit described). Description does not add explicit details for account_id/business_id but implies their role via scoping context. 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?

Clear verb (Read), specific resource (Loppee support conversations for a managed business), with details on ordering (newest first), content (full message log), and statuses. Explicitly distinguishes from siblings by scoping to this business only and pairing 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?

States when to use (reading support conversations with scoped management key, any plan) and pairing with send_support_message to reply. Implicitly differentiates from list_customer_messages by focusing on support threads, but no explicit exclusion of 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?

Annotations declare readOnlyHint=true and openWorldHint=true. The description adds significant context: it is pay-independent and does not consider payment, trust score, or category reach to decide existence. This goes beyond annotations and provides clear behavioral expectations 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 two sentences, front-loaded with the core purpose. Every word adds value, no redundancy. It is concise and well-structured, making it easy for an agent to parse 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?

The description covers the essential purpose and unique characteristics (universal, pay-independent). For a simple lookup tool, this is sufficient. However, it does not describe the return format or default behavior when location parameters are provided, which could be inferred but is not explicit.

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

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

Schema description coverage is 100% with detailed descriptions for each parameter. The tool's own description does not add new parameter-level information beyond reinforcing the universal nature of the 'name' parameter. Baseline 3 is appropriate as the schema carries the full burden.

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 is a 'Universal business-name lookup', specifying the verb (lookup) and resource (business by name). It distinguishes from siblings like search_businesses by emphasizing pay-independence and inclusivity of all record types.

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

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

The description implies when to use this tool: for a neutral, pay-independent name lookup. It explains what it does not use (payment, trust score, category reach), guiding the agent away from using it for filtered searches. However, it does not explicitly name alternative tools like search_businesses for such cases.

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

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

Annotations indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds significant context: 'This mutates deal records', 'Not idempotent for create/delete/publish transitions', auth requirements, rate limiting ('management_rate_limited'), paid-tier requirement, and that it never affects trust score.

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

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

The description is fairly long but every sentence adds value. It is front-loaded with the purpose (first sentence) and then details operations, auth, and edge cases. Minor improvement could be breaking into paragraphs for readability.

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 11 parameters and no output schema, the description covers operation semantics, auth requirements, rate limits, paid-tier restrictions, and side effects. It feels complete for an agent to use correctly.

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

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

Schema description coverage is 55% (6 of 11 parameters have descriptions). The description explains the operation enum and deal_id requirement but adds little beyond schema for parameters like terms, promo_code, description. Baseline 3 for moderate coverage with some added context.

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: creating, editing, publishing, unpublishing, or deleting a deal/coupon. It names the specific resource ('deal/coupon') and lists all five operations, distinguishing it from siblings like redeem_coupon or validate_coupon.

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 explains each operation's effect ('create makes a draft, publish takes a draft live, etc.') and advises calling get_agent_identity first. However, it does not explicitly mention when to use this tool versus alternatives (e.g., redeem_coupon for redeeming).

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 (readOnlyHint false, openWorldHint true). It details the create-as-draft behavior, publish payment flow (Stripe checkout, human must pay), idempotent delete, rate limiting, and that payment only affects 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 relatively long but well-structured: front-loaded with core actions, then payment details, then prerequisites. Every sentence adds value. Could be slightly more concise, but appropriate for the 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 complexity (27 parameters, 6 operations, no output schema), the description covers key behaviors (draft, payment, delete idempotency), prerequisites, and error scenarios (rate limit, missing posting). It does not explain the full return object, but that is expected without an output schema. Lacks coverage for some parameters but overall comprehensive.

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 44%, low. The description adds operational context for the 'operation' parameter and mentions defaults for city/state/category_alias. However, most of the 27 parameters are not individually described, leaving the agent to infer from the schema alone. Description partially compensates but not fully.

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: 'Create, edit, publish, pause, close, or delete a job posting for a business you manage'. It distinguishes from siblings by specifying it mirrors manage_business_deal, but for job postings. The verb+resource is highly 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 explicit context: requires a scoped management key, prerequisites like employer must be claimed/verified/published, and suggests calling get_agent_identity first. It explains when different operations are appropriate (e.g., create makes draft, publish takes live). However, it does not explicitly exclude alternatives or compare to other sibling tools beyond the mirror statement.

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 idempotentHint true and destructiveHint false, so the description adds minimal value. It states the tool requires a specific permission, which is useful, but doesn't describe side effects like changes to notification state or impact on listing.

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 primary action and scope. No extraneous words. Efficient and clear.

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 simplicity of the tool (no output schema, few parameters), the description is incomplete. It omits parameter semantics and practical usage context, such as when notifications appear and how marking as read affects them.

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 has 0% description coverage for three required parameters. The description does not explain what account_id, business_id, or notification_id represent, leaving the agent to infer their meaning from names alone. This is a significant 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 clearly states the action ('mark as read') on a specific resource ('owner notification') and scopes it to the business of the management agent. It distinguishes itself from siblings like list_notifications and respond_to_review.

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 mentions a permission requirement ('Requires allowed_actions include mark_notification_read') but provides no guidance on when to use this tool vs alternatives like list_notifications or other notification-related tools. Usage context is implied but not explicit.

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

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

Discloses commercial influence, 80/20 interleaving, placement rules, and that payment never affects trust scores. Goes well beyond annotations (readOnlyHint, destructiveHint) to explain algorithmic nuances.

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

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

Front-loads core purpose and then explains complex behavioral details. While somewhat lengthy, each sentence adds value; could be slightly more terse but remains 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?

Given no output schema, the description covers return format (empty array vs error), trust_card_url, citation, and exclusion criteria. Explains algorithm and commercial aspects sufficiently 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 coverage is 100% with clear descriptions for all 13 parameters. The description adds no additional parameter-level detail beyond what the schema provides, 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?

Clearly states it returns published Loppee Trust Card profiles with safe_to_recommend=true. Explicitly distinguishes from search_businesses with a specific use-case directive.

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

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

Explicitly says 'Use this — not search_businesses — when a user needs a business you will actually recommend.' Also describes exclusions and empty-result behavior. Could further clarify scenarios where search_businesses is preferred.

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 non-idempotence (each call creates a fresh checkout session and replaces previous pending redemption), that it never charges (business owner must complete payment), that redeeming counts against limits while pending, and that it cannot affect trust score, rating, etc. Annotations already indicate read-write and non-idempotent, but description adds critical flow details.

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

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

Description is somewhat long (~150 words) but well-structured, starting with main purpose then important caveats and details. Every sentence adds value, though could be slightly more concise.

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 5 parameters, no output schema, and complex side effects (checkout session, pending state, error conditions), the description is comprehensive. Covers prerequisites, process, error codes, and behavioral constraints, fully equipping 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?

Schema coverage is 100% and description adds meaning: maps tier values to plan names, notes code case- and whitespace-insensitive, advises confirming account_id with get_agent_identity, and explains business_id must be within allowed_business_ids. Provides context beyond simple 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 clearly states it redeems a coupon by creating a Stripe Checkout session with discount applied and returns a URL and price breakdown. It distinguishes from sibling validate_coupon by noting it runs the same validation then creates a checkout session, and explicitly says it never charges directly.

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 guidance: do not call speculatively—use validate_coupon instead; requires a scoped management key with matching account_id and business_id, allowed_actions including redeem_coupon, and configured billing. Also documents when to expect certain errors.

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 reply is stored and attributed, does not change trust score, and is rate-limited per plan, adding significant context beyond annotations that indicate non-readonly, non-destructive, and open-world behavior.

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

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

Two sentences front-loaded with purpose, 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?

Covers behavioral context, prerequisites, and side effects adequately, but omits the return value or response format since there is no output schema.

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

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

The description clarifies the interaction_id and body parameters, but account_id and business_id are not explained beyond the implicit context of 'on behalf of a business you manage', and schema coverage is only 25%.

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 'Post a reply' and the resource 'inbound customer message', and distinguishes it from siblings like 'list_customer_messages' and 'respond_to_review'.

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

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

Explicitly instructs to pass the interaction_id from list_customer_messages and the reply body, mentions required permissions and rate limits, but does not explicitly exclude alternative tools.

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 mutation but not destructive. Description adds critical context: reporting never removes the review, moderation is human/reactive, no impact on trust score/weighting/ranking. Also details error conditions (review_report_not_negative, etc.). 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?

Description is long but well-structured: begins with core action, key caveat, then alternatives, prerequisites, and error states. Each sentence serves a purpose. Could be slightly trimmed but remains clear and informative.

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 mutation tool with 5 parameters and no output schema, the description is remarkably complete. Covers behavior, error conditions, preconditions, and what does NOT happen. Addresses common misuse and provides sufficient guidance for an AI agent to use 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 100% of parameters. Description adds meaningful context beyond schema, e.g., clarifying reason_category values, noting that 'negative' is not a valid category, and referencing account_id from get_agent_identity. Adds value but could provide more detail on reason_detail formatting.

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?

Description states 'Report a customer review... into Loppee's moderation queue for a claimed policy violation', clearly specifying verb, resource, and scope. It distinguishes from siblings by explicitly contrasting with respond_to_review and listing supported categories.

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 (reporting policy violations) and when-not-to-use (not for negative reviews, not to suppress criticism). Names alternative tool respond_to_review. Mentions prerequisites (management key, get_agent_identity) and rate limits.

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

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

Adds significant behavioral context beyond annotations: response is public and attributed, never changes trust score/rating/weighting, specific error returns. No contradiction with annotations (readOnlyHint=false, idempotentHint=true).

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

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

Multiple sentences but each adds value; front-loaded with main action. Slightly verbose but justified by richness of context.

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?

Covers behavior, errors, permissions, rate limiting. Missing explicit success response format, but tool is a mutation and output schema not provided. Overall complete for a 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?

Schema coverage is 100% and each parameter description adds meaningful context (e.g., body's character limit, review_id source, account_id from get_agent_identity). The description reinforces idempotency via body.

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 'Publish the business's ONE public response to a customer review' and emphasizes idempotency, distinguishing it from sibling tools 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?

Provides explicit context on when to use (responding to a review), idempotency, prerequisites (scoped management key, call get_agent_identity), and error conditions. Could explicitly contrast with sibling tools like report_review.

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 irreversible action, immediate effect with no cache window, audit logging, and that a new key must be issued by the human owner. Annotations already indicate destructiveHint=true, but description adds important 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?

Thorough but slightly verbose; every sentence adds value but could be tightened. Front-loaded with core action.

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?

Covers behavior, side effects, preconditions, error conditions, and post-revocation steps. No gaps given no output schema and destructive annotation.

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 has 0% coverage for the confirm parameter. Description explains that without confirm:true, the tool returns confirm_required and changes nothing, adding essential 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?

Clearly states it revokes the API key used in the current call, irreversibly. This is a unique action among sibling tools like get_agent_identity or clear_my_location.

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 describes when to use (key exposed, integration retired, user disconnect), prerequisites (call get_agent_identity first), requirement for confirm:true, and error cases (env_key_not_revocable).

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 provide idempotentHint, destructiveHint, etc. Description adds 'Idempotent: saving the same business twice is a no-op' and 'Saving never affects the business's trust score, ranking, or reviews', which are beyond annotations. 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?

Five sentences, each adding distinct value: purpose, round-trip, auth constraints, idempotency, nondestructive effect, error returns. No redundancy. Front-loaded with purpose.

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

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

Lacks output schema. Description covers behavior, auth errors, but does not describe return format or success response. With 8 parameters, optional ones are not explained. Adequate but with 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?

Schema description coverage is 0%. Description does not elaborate on individual parameters beyond listing required ones (account_id, business_id, business_name, business_source) in context. Optional parameters (city, notes, state, category) lack semantic explanation. Description adds some value by stating requirements but fails to compensate fully for low 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?

Description clearly states 'Attach a published business or directory listing to a customer/service-agent account workflow (a shortlist — it does not contact the business).' It uses a specific verb and resource, and distinguishes from sibling tools like list_saved_businesses and unsave_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?

Description explains when to use this tool ('shortlist round-trips: read it back with list_saved_businesses and prune entries with unsave_business') and prerequisites (valid scoped agent API key, account_id match). It does not explicitly state when not to use, but 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?

Description discloses commercial influence (share-of-voice) while affirming read-only safety (readOnlyHint, destructiveHint). Adds context about ranking, reach, unverified listings, and IP fallback, beyond what annotations 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?

Description is verbose with dense technical details, though front-loaded with the key verb and resource. Could be more concise but remains well-organized.

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?

Covers main behavioral aspects but omits output structure beyond suggestions block. No pagination details or response fields described, which is notable given no output schema.

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

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

Schema has 100% description coverage, so baseline is 3. The description adds overarching context for q (auto-routing) and location fallback, but individual parameter descriptions in schema are already detailed. Slight value add.

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 is a backward-compatible discovery search that auto-routes free text, distinguishing between category and name lookup paths. It differentiates from sibling tools like search_category and lookup_business by explaining the unified routing behavior.

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 guidance on when to use category vs name routing, how to handle location (fallback vs explicit), and how to interpret zero-result responses. Recommends passing explicit location when known and explains the intent parameter for forced routing.

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

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

Discloses read-only nature, explains that unclaimed listings are marked and ranked after published results, details that payment does not affect trust scores or recommendations, and outlines location confidence effects. All behaviors are consistent with annotations (readOnlyHint, openWorldHint, destructiveHint).

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

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

The description is well-structured and front-loaded with the main purpose. While it is lengthy, each sentence provides necessary context; it could be slightly trimmed but is 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 10 parameters, no output schema, and complexity (suggestion logic, location fallbacks, payment implications), the description covers all behavioral aspects comprehensively. Everything an agent needs to invoke correctly is addressed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining how colloquial phrasings resolve, the fallback location behavior, and the meaning of safe_to_recommend. It enhances understanding beyond 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 clearly states it is for 'reach-gated category/area discovery' using taxonomy aliases, specifies it is read-only, and distinguishes it from general business search tools by clarifying it queries published and unclaimed discovery listings with ranks. The verb 'search' is implied, and the resource 'categories' is explicitly noted.

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 guidance on when to use this tool for category discovery, explains location parameter behavior (fallback to IP when none provided), and gives context on how unresolved terms yield suggestions. It does not explicitly compare to siblings but clearly sets expectations for input and output.

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 readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds substantial behavioral context: results include JSON-LD, location fallback behavior, payment's limited role, and inclusion of remote roles. 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 relatively long but well-structured with colons and line breaks. Every sentence adds value, covering purpose, usage, and edge cases. Minimal redundancy, but could be slightly more concise.

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 19 parameters, no output schema, and no nested objects, the description is remarkably complete. It explains defaults, fallbacks, edge cases (remote roles, salary computation), and the non-ranking nature of payment. No obvious 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?

Schema description coverage is 100%, so baseline is 3. The description adds significant meaning beyond parameter names, such as explaining the location fallback logic, typo-tolerant search, and that salary_min excludes undisclosed salaries. This justifies a score of 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 tool discovers 'active schema.org-aligned Loppee Jobs postings' from Trust Cards, specifying the resource (job postings), action (search), and source (Trust Cards). It distinguishes from sibling tools like search_businesses by focusing exclusively on job postings.

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 detailed guidance on location parameters (use lat/lng, zip, or city/state; fallback to IP-derived location) and advises passing explicit user location. It also clarifies payment only affects eligibility, not ranking. However, it does not explicitly contrast with sibling tools like search_businesses or search_category.

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=false, openWorldHint=true, etc.), the description reveals critical behaviors: no human pre-moderation, direct delivery, business must be published on a paid tier, character limits, auth errors, and that sending never affects trust score/ranking. This adds substantial 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 description is long but well-structured: core action first, then delivery behavior, business requirements, error handling, repeat behavior, limits, auth, and side effects. Every sentence adds value. It could be slightly more concise, but the organization is logical and front-loaded.

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 (6 required params, no output schema, sparse annotations), the description is remarkably complete. It covers prerequisites, error handling, side effects, limits, and even distinguishes from similar tools. No significant 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?

Schema coverage is 0%, so the description must compensate. It explains that target_business_name is resolved from the registry (not used for identification), and gives character limits for subject and message. However, it does not explain target_business_id, target_business_source, or account_id beyond mentioning that it must match the key. Some parameters remain underspecified.

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: 'Send a message to a business on behalf of the calling customer account.' It specifies the verb (send), resource (message to a business), and agent (calling customer account). It distinguishes from siblings like list_my_conversations (read replies) and reply_to_customer_message (reply). The purpose is 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 explicit usage context: it says 'do not retry a blocked send', explains that repeat sends append to an existing conversation, and mentions that blocked attempts for free/unclaimed businesses are recorded. It also states prerequisites: 'Requires a valid scoped agent API key' and suggests calling get_agent_identity first. It implies alternatives like list_my_conversations for reading replies. This is thorough 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?

The description extensively details behavior beyond annotations: reopening behavior, scoping, auth requirements, rate limiting, no impact on trust score or ranking, attribution in audit log, and plan tier constraints. Annotations are consistent (readOnlyHint=false, destructiveHint=false) and description adds rich 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 thorough but each sentence adds value. It front-loads the main action and then details behavior and constraints. Slightly long but justified by the complexity of the tool's behavior.

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 4 parameters and no output schema, the description covers all essential aspects: what the tool does, when to use it, behavior of ticket management, authentication, rate limits, side effects (no trust score impact), and parameter constraints. It is complete for reliable agent 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?

With only 25% schema coverage, the description adds critical semantics: body is described as ≤4000 chars and required; subject is optional, ≤160 chars, and only for new tickets; account_id and business_id are implied as identifiers. It compensates well for schema gaps.

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: 'Post a message to Loppee support on behalf of a business you manage.' It uses specific verbs and resources, and distinguishes from sibling tools like list_support_messages by focusing on creating vs listing messages.

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 explains when to use the tool (to contact support, reopening or creating tickets) and its scope (this business only). It does not explicitly contrast with sibling tools like reply_to_customer_message, but the domain difference is implied. The context is clear enough for correct selection.

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

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

The description fully discloses behavioral traits beyond annotations: it explains the idempotent replace semantics, the ability to clear with null, server-side timezone derivation, and the non-impact on scoring. It aligns with annotations (idempotentHint=true, destructiveHint=false) and adds valuable context about authentication and side effects.

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 lengthy but each sentence adds essential detail. It is front-loaded with the core action and idempotent nature. Could be slightly more concise, but the complexity of the hours structure justifies the length. Well-organized into a single paragraph with clear logical flow.

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 of the tool (nested structure, multiple states), the description covers all necessary aspects: input requirements, clearing, timezone handling, authentication, and lack of ranking impact. No output schema exists, so no need to explain return values. All sibling tools are distinct, and this one is fully self-contained.

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

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

Despite low schema coverage (33%), the description provides comprehensive details for the 'hours' parameter: the structure of weekly and overrides, allowed statuses, time format ('HH:MM'), range constraints (1-4, non-overlapping, open<close), and the null case for clearing. It compensates fully for the schema's lack of inline 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 clearly states the action is to 'Set (or clear) the structured operating hours' and specifies the resource (a business you manage). It distinguishes the tool from siblings by emphasizing that it performs the same validated write as the owner's dashboard, which is unique among the 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 explains when to use the tool (to set/clear hours) and provides prerequisites (requires scoped management key with update_business_profile action). It also clarifies that hours are informational only and do not affect trust/ranking, but does not explicitly contrast with alternatives like get_business_profile for reading hours.

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 (idempotent, not read-only), the description adds critical behavioral details: it is a mutation that becomes the default discovery anchor, requires user confirmation, and mandates authentication with matching account_id. 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 the core action, then progressively adds usage guidance, authentication requirements, and caveats. Every sentence provides necessary information without redundancy.

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

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

The description covers purpose, usage, parameters, side effects, and security. However, it lacks any mention of the return value or success confirmation. While not critical, it slightly reduces completeness. Output schema is absent, so description could have included that.

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%, baseline 3. The description adds mutual exclusivity of zip vs lat/lng, clarifies label purpose, and expands on account_id requirement (match with key). This adds substantial value beyond 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 explicitly states the tool saves or replaces a home location, distinguishing it from siblings like get_my_location or clear_my_location. It specifies the accepted formats (zip or lat/lng) and optional label.

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 explains the effect on search default and instructs to confirm with user before saving. It mentions explicit coordinates override, but does not explicitly compare to alternatives like get_my_location or clear_my_location. However, it effectively sets context for when to use.

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 idempotentHint=true and destructiveHint=false, which the description confirms by stating that submitting again edits the existing review (idempotent). The description adds critical behavioral details not in annotations: reviews are display-only, never affect trust scores or search ranking, payment doesn't affect display, verified transaction badge conditions, removal only by human moderator. 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 lengthy but every sentence adds necessary context. It is front-loaded with the core purpose. Slight structural improvements could be made (e.g., listing key rules separately), but overall it is efficient and informative.

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 most aspects: idempotency, display impact, badge conditions, removal policy, authentication. However, it lacks an explicit explanation of the success output (e.g., what the tool returns upon successful submission/editing). Since there is no output schema, describing the return value would improve completeness. The description is otherwise thorough.

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 must compensate. The description provides context for some parameters (e.g., rating range 1-5, account_id matching API key) but doesn't explicitly describe each property. It mentions 'target_business_source' and 'subject' without further detail. However, the business logic context (e.g., verified transaction badge) indirectly clarifies some parameters. The description adds moderate value but leaves some parameter semantics 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 verb 'Submit (or edit)' and the resource 'first-party customer/service-agent review (rating 1-5) for a business'. It distinguishes from sibling tools like report_review and respond_to_review by specifying it's for first-party reviews and that it creates/edits rather than reports or responds.

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 (submitting or editing a review) and when not to (no anonymous review, no pre-moderation). It also provides authentication requirements (scoped agent API key with matching account_id) and suggests calling get_agent_identity first. It notes that the review is published immediately and there is at most one per account-business pair, making usage conditions 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?

Beyond the annotations (idempotentHint, destructiveHint), the description adds valuable behavioral details: returns removed=false for no-op, does not affect business trust score/ranking/reviews, and specifies auth error types. This fully informs the agent of side effects.

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 paragraph with clear front-loading of the main action, followed by details. It is efficient but could be split into bullet points for easier scanning. No wasted sentences.

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

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

Given no output schema, the description covers return behavior for both success and no-op, auth error scenarios, and idempotency. The tool has only two simple parameters, so the description is 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 coverage is 100%, so the description adds little beyond what the schema already provides. The tip to confirm account_id via get_agent_identity is helpful but minor. 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 uses a specific verb ('Remove') and resource ('saved-business shortlist') and clearly distinguishes from the sibling tool 'save_business' by calling it 'the prune half'. It unambiguously states what the tool does.

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

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

The description explains when to use the tool (to unsave a business) and provides important context: idempotent behavior, scope restrictions, and required API key conditions. It does not explicitly list alternatives or when-not-to-use, but the purpose is clear enough.

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 annotations: gallery photos enter a moderation queue while logo/cover publish immediately, SVG sanitization, file size limits, rate limits, and the guarantee that photos don't affect trust score or verification. Annotations only indicate destructiveHint=true and idempotentHint=false; the description fills in all behavioral details.

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

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

The description is a single paragraph but well-structured, starting with the main verb and then breaking down each kind's behavior. It is dense with information but not overly verbose; could be slightly more concise but remains clear.

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 (9 parameters, no output schema), the description is remarkably complete: it covers all operations, kinds, file constraints, moderation pipeline, auth, rate limiting, and side effects. No critical gaps are 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?

With 67% schema coverage, the description compensates by explaining the meaning of 'kind' enum values (gallery vs singleton), the relationship between operation, asset_id, and file_name, and the format/size constraints. It adds value beyond the schema's brief parameter 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 clearly states the tool's purpose: 'Add or remove branding media for a business you manage' and enumerates the three kinds (business_photo, logo, cover_photo) with distinct behaviors. It differentiates from siblings by focusing specifically on branding photo management, which is not covered by other tools like update_business_profile.

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 guidance for when to use add vs remove, and the different behaviors for each kind (gallery vs singleton replace-in-place). It also explains auth requirements and rate limiting. However, it does not directly contrast with alternative tools, though the specificity reduces ambiguity.

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?

Description adds substantial context beyond annotations: idempotency, overwrite behavior, auth requirements, rate limiting, and restrictions on non-editable fields. Annotations already provide idempotentHint, but description elaborates.

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?

Dense but not verbose; every sentence adds value. Front-loaded with purpose and field list, then covers overwrite/idempotency, category specifics, auth, rate limits, and exclusions. No wasted words.

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 10 parameters with low schema coverage and no output schema, the description covers behavior, constraints, and requirements well. Missing return value details but acceptable for a 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?

With only 10% schema description coverage, the description adds meaning for many parameters (display_name, category, website, phone, city, state, zip) and explains the category_aliases requirement. Compensates well for schema gaps.

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?

Clearly states it updates editable profile fields for a managed business. Lists specific fields (display_name, category, etc.) and distinguishes itself from other business tools by focusing on profile editing.

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 context: required auth (management key), rate limiting, category requirements (requires category_aliases from taxonomy endpoint), and what cannot be edited. Could be improved by explicitly stating when not to use or 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?

Discloses idempotency, visibility to seeker, audit logging, no impact on trust/ranking/account, key requirements, rate limits, and error behavior (job_application_not_found). Adds significant value beyond annotations (idempotentHint, destructiveHint).

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?

Single dense paragraph front-loads main action, then covers constraints, behavior, requirements, and errors efficiently. Every sentence adds value with no repetition 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?

Covers purpose, valid statuses, idempotency, side effects, prerequisites, rate limits, and a specific error case. Despite no output schema, the description provides sufficient 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 coverage is 100% with descriptions; description adds meaningful context for each parameter (e.g., status explanation, sources like get_agent_identity, constraints like allowed_business_ids).

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 'Set' and the resource 'employer-side status of one application', lists valid statuses, and explicitly distinguishes from applicant withdrawal, differentiating it from sibling tools like withdraw_job_application.

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 context on when to use (employer status update) and constraints (applicant-only withdrawal); mentions prerequisites (scoped management key) and rate limits. Does not explicitly name alternative tools but strongly implies them.

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?

Reinforces annotations (readOnlyHint, destructiveHint) with explicit statements. Discloses non-effects on trust score, ranking, etc., and lists failure modes. Adds value beyond annotations with detailed 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?

Somewhat long but well-structured and front-loaded. Every sentence serves a purpose (purpose, read-only, prerequisites, distinction, failures, non-effects). Could trim slightly, but efficient given 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?

Covers purpose, return fields, prerequisites, failure codes, and non-effects. With no output schema, description adequately lists return fields. Slightly lacking exact JSON structure, but otherwise complete for a complex 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?

Schema coverage is 100%, but description adds extra meaning: code case-insensitivity, tier-to-plan mapping, period default. Provides usage guidance for account_id and business_id. Above baseline 3.

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

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

The description clearly states the tool validates a coupon against a business and plan, returning pricing details. It uses specific verbs ('check') and resources ('coupon', 'business', 'plan'), and distinguishes from siblings like 'redeem_coupon' and 'manage_business_deal'.

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/why: read-only, prerequisites (get_agent_identity), limitation to Loppee-issued coupons vs. own deals, and failure codes. Clearly tells when not to use and points to alternative 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?

The description thoroughly explains idempotent behavior (already_withdrawn=true), effects on application status (flipped to withdrawn, nothing deleted), and what is NOT affected (employer trust score). This goes well beyond the annotations, providing full 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 a single paragraph but packs in essential information without fluff. It could be slightly more structured, but it remains concise and 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?

Given the tool's complexity and lack of output schema, the description covers idempotency, re-application, effects, and error conditions adequately. It omits explicit return format but provides enough context 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?

Schema covers 100% of parameters with descriptions. The description adds useful context, such as the source of application_id and the requirement that account_id matches the key, which aids correct invocation.

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 'withdraw' and the resource 'own job applications'. It distinguishes from sibling tools like update_job_application_status by specifying the behavior and scope, making the purpose unambiguous.

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

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

The description explains when to use the tool (to withdraw own applications) and what prerequisites are needed (matching key and account_id). It does not explicitly state when not to use, but the context is clear enough.

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