ReputeMap

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

Annotations already set readOnlyHint=false and idempotentHint=false, so write behavior is partially declared. The description adds real value beyond them: drafts use the business's saved voice/sign-off, get persisted into the app editor, and never publish. It does not address repeat-invocation behavior or whether drafts overwrite previous ones.

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 dense sentences with the non-publishing guarantee front-loaded in a memorable caps phrase. No filler.

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

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

No output schema exists, yet 'generate 2-3 reply drafts' gives a usable sense of the return. Coverage of persistence and scope is strong; only the exact response shape and repeat-call behavior remain unspecified.

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% (review_id sourced from list_reviews, instructions as optional one-off guidance), so the schema carries the parameter load. The description adds only that generation is tuned by saved voice and sign-off, which is not parameter-level detail.

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

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

States a specific verb+resource: generate 2-3 reply drafts for one review and save it so it appears in the editor. The 'NEVER publishes anything - drafts only' line cleanly separates it from the sibling publish_reply.

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?

Makes clear when this tool applies (generating drafts, not publishing) and implicitly points to publish_reply as the separate step. It lacks an explicit 'use publish_reply to send' signpost, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is safe. The description adds behavioral context about the trailing window (default 30 days) and specific metrics returned, which is valuable 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?

A single concise sentence that conveys all essential information without 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?

With no output schema, the description lists the metrics returned, which is adequate. However, it could be more explicit about the structure (e.g., per-location objects vs totals).

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% (days parameter lacks description in schema). The description adds the default 30 days and the concept of a trailing window. For location_id, both schema and description cover omission for all locations. Description adds some value but does not fully compensate for the missing schema description of days.

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 provides 'Review stats per location and org totals' listing specific metrics, distinguishing it from sibling tools like list_reviews (individual reviews) and list_locations (just locations).

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

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

The description implies usage for aggregate stats but does not explicitly state when to use this tool vs alternatives like list_reviews for individual reviews or send_review_request for sending requests.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that usage is 'current month' and 'shared between REST API and MCP tools,' which provides some context beyond annotations. However, it does not describe output format or potential rate limits.

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?

A single, clear sentence that is front-loaded and contains no redundant 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?

For a parameterless tool with annotations covering safety, the description sufficiently explains what the tool returns (current month usage, org-level, shared). No output schema exists, so a bit more detail on return format could be added, but 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?

The tool has zero parameters and schema coverage is 100%. Per guidelines, baseline is 4. Description does not need to add parameter meaning since there are none.

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 current month's API credit usage for the organization, specifying the resource (usage credits) and verb (get). It distinguishes itself from siblings like get_review_stats and list_locations, which deal with different data.

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 does not provide any guidance on when to use this tool versus alternatives. It simply states what it does without context for selection among siblings.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description adds minimal behavioral context beyond stating it returns a list. It does not contradict annotations and provides the scope ('every business location this ReputeMap org manages').

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 sentence that conveys purpose and key detail (IDs for other tools) without unnecessary words. It is front-loaded and 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 the tool has no parameters, no output schema, and is a simple listing operation, the description provides sufficient context: it lists all locations managed by the org and highlights the usefulness of IDs. Sibling tool names clarify the tool's distinct role.

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?

There are no parameters, and schema coverage is 100%, so the description does not need to elaborate. The mention of 'ids' pertains to the output, not parameters, and 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 the specific verb 'list' and clearly identifies the resource as 'business locations'. It also mentions the purpose of providing IDs for other tools, which distinguishes it from sibling tools that operate on reviews, stats, or requests.

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 that this tool should be used first to obtain location IDs for use in other tools, but it does not explicitly state when not to use it or provide comparisons to siblings. The context is clear but could be more directive.

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 establish read-only/idempotent/non-destructive, so the safety profile is covered. The description adds substantive behavior beyond that: newest-first ordering, inlined published reply text, Google's moderation states (approved/pending/rejected), and the specific consequence that a rejected reply makes has_reply false with reply_policy_violation explaining why. It omits pagination behavior and any rate/volume caveats.

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 carrying distinct information: the core listing behavior first, then filters, then reply-state semantics. No filler or repetition of the name/title, and the most decision-relevant content is 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?

With no output schema, the description carries the return-shape burden and does so by naming the key response fields (inlined reply text, reply_state, has_reply, reply_policy_violation). Combined with the filter list and the moderation-state explanation, an agent has enough to call this correctly and interpret results.

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

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

Schema coverage is only 43%, so the description must compensate, and it does for five of seven parameters: location_id (via 'location'), rating_min/rating_max (via 'star-rating range'), unanswered_only (via 'replied/unreplied'), and since_days (via 'trailing day window'). It does not clarify limit/offset paging or the default/max page size, which are undocumented in the schema as well.

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

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

States a specific verb and resource ('List Google reviews for the org'), plus ordering ('newest first') and the inlined reply text. This differentiates it from siblings like get_review_stats (aggregates) and list_locations, letting an agent identify it without opening the schema.

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

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

Enumerates the available filters (location, star-rating range, replied/unreplied, trailing day window) and tells the agent what to do when a reply is rejected ('write a new reply'), pointing implicitly at the reply tools. It gives clear usage context but does not explicitly state when to prefer this over get_review_stats or other 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 already flag destructiveHint=true and openWorldHint=true, and the description adds substantial context beyond them: the action is publicly visible, refused text persists in ReputeMap under 'manual_required', and Google moderation produces 'pending' and 'rejected_by_google' states with policy_violation detail. This is exactly the kind of outcome behavior an agent needs before calling.

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

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

Front-loaded with the action and its public nature, then conditions, then failure modes. Every sentence carries distinct decision-relevant information with no 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 2-parameter mutation with no output schema, the definition covers approval precondition, external visibility, fallback persistence, and moderation outcomes — everything an agent needs to call it safely and interpret the result.

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

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

Schema description coverage is 100%, so both parameters (text, review_id) are already documented, including the 'exact approved text' and 'UUID from list_reviews' notes. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (PUBLISH) and resource (reply to this review's public Google profile) with clear scope, and the 'public, customer-visible' framing separates it from the draft_reply sibling without needing to name it.

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?

Gives an explicit precondition — call ONLY when the user has explicitly approved this exact text — plus guidance to write a different reply when Google rejects it. It stops short of naming draft_reply as the alternative for un-approved text, which is the one inference left to the agent.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses that it emails a real person, respects unsubscribes and suppression lists, and explains return statuses including 'already_requested' with no second email or credit spent. This is rich behavioral context for a side-effectful tool.

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

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

Two sentences, front-loaded with the core action and immediately followed by the critical caveat and return statuses. Every word earns its place, 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?

Given no output schema, the description sufficiently explains the possible return values and side effects. It covers when to use, what happens (respects suppression), and important outcomes (already_requested prevents duplicate sends). The location_id prerequisite is covered in the schema.

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

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

Schema description coverage is 100% (all three parameters have descriptions), so the description adds no additional parameter meaning. Baseline 3 applies; the description's mention of statuses does not directly clarify parameter usage 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 sends a single review-request email to a real customer via ReputeMap's campaign engine. The verb 'Send' plus the specific resource 'review-request email' makes it distinct from the sibling read-only tools (get_review_stats, list_reviews, etc.).

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

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

It explicitly states 'only use it when the user explicitly asks to request a review,' providing a clear condition for use. It does not name an alternative tool, but the guidance is strong enough to prevent misuse.

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