AdvocateMCP

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context beyond annotations: the derived-from-hours-only nature and the caveat that windows may already be held. It doesn't describe pagination or limits, but with an output schema present and strong annotations, the added context is quite good.

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 core purpose, followed by a critical caveat. No wasted words. Loses a point only because the caveat could arguably be flagged even more prominently, but overall it's efficient 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?

With an output schema present, return-value explanation isn't needed. The read-only nature is covered by annotations, and the description covers the key caveat about availability not being live. It's complete enough for the agent to use correctly; could mention timezone handling, but that's a minor gap given the overall quality.

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 all three parameters (slug, window_start, window_end) already have descriptions in the schema. The description mentions the 30-minute window granularity and adds that the windows are time-based, but doesn't add meaning beyond what the schema provides. Baseline 3 is appropriate given full schema coverage.

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

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

The description states a specific verb+resource ('Return 30-minute availability windows for a business') and clearly scopes the data source ('based on its configured operating hours'). It distinguishes itself from siblings by explaining what it does NOT do (check live bookings), which differentiates it from reserve_slot and sets expectations clearly.

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 it ('to show a user when a business is open for appointments') and, crucially, states when not to rely on it: windows are not checked against a live booking calendar or reservations, so a returned window may already be held. This tells the agent when alternate tools (like reserve_slot) are needed for actual confirmation.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable context that the response includes 'agent guidance on how to frame the policy with appropriate freshness caveats,' going beyond what annotations provide. This is useful behavioral detail without redundancy.

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 with the main action front-loaded. The first sentence states the purpose, the second gives usage guidance and response details. There is no wasted wording; 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?

For a simple read-only tool with one parameter and an output schema, the description covers the essential aspects: what it returns, when to use it, and the nature of the response. Sibling tools are all clearly different in purpose, and the description is complete without needing to explain return values since an output schema exists.

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

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

Schema description coverage is 100%, as the only parameter 'slug' is described as 'Business slug identifier.' The description does not add additional parameter semantics, but the schema fully covers it. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Returns the business's cancellation policy text.' This is a specific verb and resource, and it distinctly differs from sibling tools like get_availability or get_quote. The purpose is immediately evident.

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: 'Use this when a user asks about cancellation terms, fees, or no-show policies.' It gives clear direction on when to use the tool, though it doesn't explicitly mention when not to use it or name alternative tools for other scenarios.

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 a key behavioral insight beyond the annotations: 'The response carries explicit "self-reported" framing so agents don't upgrade tenant claims to verified facts.' This tells the agent about the trustworthiness of the data and how to handle it, which is not conveyed by readOnlyHint or idempotentHint. 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 two sentences, tightly packed with information: the resource returned and the specific use case plus behavioral caveat. Every sentence adds value, with no filler or repetition of schema/annotation content.

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

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

For a simple tool with one parameter, an output schema, and strong annotations, the description covers purpose, usage context, and a critical behavioral caveat. It does not need to explain return values since an output schema exists. It is fully sufficient for an agent to select and invoke this tool correctly.

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

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

The schema already provides 100% coverage with a description for 'slug' ('Business slug identifier'). The tool description itself does not add extra parameter details, which is acceptable given the high schema coverage. It does not detract or enhance beyond the baseline.

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 specific verb 'Returns' and clearly identifies the resource: 'business's self-reported licenses, insurance, bonding, and certifications.' This distinguishes it from sibling tools like get_availability or get_cancellation_policy, which cover different aspects of a 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 gives explicit context for when to use the tool: 'for trust-sensitive verticals (contractors, healthcare, legal, locksmiths) when a user asks "are they licensed?" or "are they insured?".' This provides clear usage guidance, though it does not explicitly mention when not to use it or name alternative tools.

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

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

Annotations indicate idempotent and non-destructive behavior, but readOnlyHint is false. The description adds important behavioral nuance: quotes may be 'exact figures' or 'estimates with a disclaimer' depending on whether configured pricing exists. This goes beyond the safety profile provided by annotations.

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

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

The description is three sentences long, each serving a clear purpose: state function, describe behavior, and give usage guidance. It is front-loaded with the core action and contains no redundant or filler content.

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

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

Given the tool's relative simplicity, an output schema exists, and the description covers purpose, behavior, and usage, the description is fairly complete. It could potentially mention how params affect the quote or what the response contains, but the output schema handles return value expectations. A slight gap in error/edge-case behavior prevents a 5.

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

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

Schema description coverage is 100%, so the schema fully documents slug, params, and service. The description reinforces that the tool quotes a service at a business, but does not add substantial parameter-level semantics beyond what the schema already 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's function: 'Quote price for a service at a business.' It uses a specific verb ('Quote') and resource ('price for a service at a business'), and distinguishes it from sibling tools by focusing on pricing queries. The addition of exact vs. estimated quotes further clarifies scope.

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

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

The description explicitly provides usage guidance: 'Use this when a user asks "how much does X cost?" or "what's the price for Y?"'. This is clear and actionable, though it doesn't explicitly mention when not to use it or alternative tools, which would warrant a 5.

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

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

Annotations declare destructiveHint=true, openWorldHint=true, and idempotentHint=true. The description adds valuable context: it explains the idempotency mechanism concretely (re-using the key returns original handoff), specifies that the server composes the notification body, and notes that supplying both message and reason is an error. This complements the annotations rather than merely restating them, though it doesn't detail auth requirements or what the response contains.

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

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

Three sentences, each earning its place: the first defines the tool's two modes, the second clarifies field responsibilities (server composes body, callers supply contact/reason), and the third documents idempotency. No Waste words, though it could arguably be slightly tighter. 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?

For a 12-parameter, no-output-schema tool with complex mode-dependent field semantics, the description covers the key ambiguity well: explaining mode-specific fields, the server-composed body behavior, the message/reason alias trap, and idempotency. It doesn't enumerate which fields map to which mode explicitly (e.g., purpose/agent_id for agent mode, contact_* for human), but the schema descriptions partially cover this and the description gives the critical guidance needed.

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

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

Schema description coverage is 100%, so all 12 parameters have individual descriptions. The tool description adds general field-roles guidance (which mode uses which fields, and that message is a deprecated alias for reason). However, most of the parameter meaning is already carried by the schema descriptions, so the description provides marginal incremental value beyond flagging the message/reason relationship and mode-field mapping.

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 (initiate/begin), names the resource (handoff), and clearly identifies the two modes (human operator vs. agent continuation). It distinguishes itself from siblings like request_callback (which likely just schedules a callback) by explaining the two-mode structure and the idempotent key behavior, adding scoping details.

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 explains when to use human vs. agent mode ('SMS/email via lead_routing_json' vs. 'signed continuation URL'), clarifies that callers supply contact and reason fields rather than message text, and documents idempotency behavior (re-using a key returns the original handoff). This provides clear context for choosing this tool over request_callback or query_business_agent.

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

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

The description discloses a key behavioral constraint not captured in annotations: 'The answer is grounded ONLY in the business's public profile.' It also describes the response format (citation-ready answer plus referral link), adding value beyond the annotations provided.

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 with the core action and output front-loaded, followed by a focused usage guideline. Every sentence adds value—no fluff or repetition.

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 purpose, usage, output format ('citation-ready answer plus a referral link'), and a key constraint (grounding). It lacks explicit exclusions or preconditions, but is sufficiently complete for this scope.

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 each parameter already described (slug, query, stage, agent_id). The description doesn't add parameter-specific details, but the baseline of 3 applies because the schema does the heavy lifting.

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

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

The description uses a specific verb 'Ask' with a clear resource ('registered business's AI advocate') and states the output ('citation-ready answer plus a referral link'). It distinguishes itself from sibling tools like get_availability or get_quote, which target narrower actions.

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: 'Use this when a user asks something specific about one business (services, hours, policies, fit).' It doesn't explicitly name alternatives or say when not to use, but the usage scenario is clear and implies sibling tools cover other scenarios.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description reinforces idempotency by explaining re-used keys return the original request. The description adds behavioral context about notification via lead routing channel (SMS/email). This adds value beyond annotations by explaining what happens on submission. No contradiction with annotations.

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

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

Two sentences with zero filler. The description is front-loaded with the core action and then provides the idempotency caveat. Efficient and purposeful, though it could slightly expand on when to use it without becoming verbose.

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 write operation with 9 params, all thoroughly documented in the schema, the description covers the essential behavioral aspects: notification mechanism and idempotency semantics. No output schema exists, so it doesn't describe the return value beyond mentioning the idempotency behavior. Given the schema richness (100% coverage, enums defined), this is reasonably complete.

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

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

Schema description coverage is 100% (the schema documents all 9 parameters), so per rubric baseline is 3. The description does not add parameter detail beyond the schema—it doesn't clarify format, precedence, or relationships between params. It's an adequate baseline since the schema thoroughly documents each field.

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

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

Description clearly states the verb+resource: 'Submit a callback request on behalf of a user.' It also explains the business notification mechanism and idempotency behavior. However, it doesn't explicitly distinguish itself from siblings beyond the obvious difference (none of the siblings appear to do callback requests), so a slight deduction.

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

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

The description states it submits callback requests and mentions the notification routing channel. It implies when it should be used (when a user wants a callback), though it doesn't explicitly state when NOT to use it or name alternatives. The sibling context (reserve_slot, initiate_handoff) suggests related but different purposes but the description doesn't directly compare.

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=false, idempotentHint=true, and destructiveHint=true. The description adds genuine value beyond this: the 15-minute expiry window, the requirement to confirm via /a2a/confirm, the HMAC-signed token return, and the idempotency semantics (same key returns original). These behavioral details (expiry, confirmation step, signed token) go well beyond what annotations provide, though a 5 might note no explicit mention of irreversible effects from the destructive hint.

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 tight sentences, each earning its place: purpose/duration, confirmation+expiry mechanics, and idempotency semantics. Zero filler, front-loaded with the core action. Ideal density for a tool with this 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?

For a 6-param mutation tool with 100% schema coverage and no output schema, the description covers the essentials: action, duration, confirmation path, expiry, and idempotency. The return value is described (HMAC-signed token, held reservation) even without an output schema. Minor gap: doesn't mention what happens on failure or insufficient availability, but given schema richness this is largely complete.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters. The description adds the idempotency_key re-use semantics, which enriches that parameter's meaning, but otherwise doesn't add format or syntax details beyond schema. Baseline 3 is appropriate since the schema does the heavy lifting; the idempotency explanation provides modest added value.

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

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

The description uses a specific verb+resource (Reserve a 30-minute time slot) and clearly distinguishes this from siblings like get_availability and request_callback. It conveys the fixed 30-minute slot duration and the 'at a business' target, 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 clearly implies when to use (to reserve/held a time slot) and explains the confirm-via-/a2a/confirm flow and idempotency behavior. However, it doesn't explicitly contrast with alternatives like request_callback or get_availability, which could merit a 5 but isn't strictly required given the clear primitives involved.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral details beyond annotations: it returns slugs, matches against multiple business fields, and positions itself as a pre-query discovery tool. 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 two tightly written sentences: the first states action, criteria, and output; the second gives a clear use-case directive. Every word earns its place 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?

For a simple list/search tool with full schema coverage, an output schema, and robust annotations, the description provides the essential context: what it searches, what it returns (slugs), and how it fits into the workflow. Nothing significant is missing.

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

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

The input schema fully covers both parameters with detailed descriptions (search matches business name, description, services, and category; location narrows geographically). The description adds no new parameter-level meaning beyond what the schema already 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?

The description uses a specific verb ('Search') with a clear resource ('registered businesses') and criteria ('by category, name, or location'). It also states the output (list of matching businesses with slugs), and distinguishes itself from sibling tools by framing this as the discovery step before querying a 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?

Explicitly states when to use the tool: 'Use this to discover which businesses are available before querying one.' This gives clear workflow context, though it does not name alternative sibling tools or explicitly state 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?

Annotations already declare destructiveHint=true, so the mutation nature is covered. The description ADDS the key behavioral traits beyond annotations: requires email confirmation via a URL valid for 7 days, and the idempotency semantics (re-using key returns original subscription). These are valuable additions that annotations don't convey. Note: annotations say idempotentHint=true, and the description confirms idempotency — consistent.

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, zero wasted words. Front-loads the core action, then covers the two critical call-enabling behaviors: confirmation URL requirement and idempotency. 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?

For a subscription tool with no output schema, the description covers the essential flow: subscribe → get confirmation URL → click within 7 days. The idempotency behavior is documented. It doesn't describe the output/return format in detail, but there's no output schema and the core semantics are adequately conveyed. Mostly 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 baseline is 3. The description adds value by clarifying that contact_email is 'confirmed via returned token' and that topics are 'topic tags' with examples. The idempotency_key semantics are well explained in the description ('re-using same key returns original subscription'). This goes beyond the schema's minimal 'Idempotency key' label.

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

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

The description states a specific verb+resource: 'Subscribe a user's email to updates from a business.' It clearly distinguishes this from siblings (search_businesses, get_quote, etc.), which are read/query operations. Loses a point because it doesn't explicitly differentiate this subscription tool from query_business_agent or request_callback, which could also be interpreted as engagement tools.

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

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

The description gives clear context (subscribe business updates, confirmation URL, 7-day validity, idempotency behavior). However, it doesn't explicitly state when NOT to use this tool or name an alternative. The 7-day confirmation constraint and idempotency note provide good operational context.

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