GBPly

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

Annotations declare readOnlyHint=true and idempotentHint=false; the description reinforces this with 'Nothing is saved or published', which is valuable confirmation that side effects are zero. It does not, however, disclose that repeated calls may yield different output (consistent with idempotentHint=false) or whether credits are consumed by AI generation.

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 short sentences, front-loaded with the action and the no-side-effects guarantee, with the sibling routing packed into the close. 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?

The description does convey the essential shape of the result (suggested Q&A pairs) and that nothing persists, which matters given there is no output schema. But with three undocumented parameters and no note on credit cost or output variability, key calling details are missing.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it never mentions profile_id, category, or instructions. The agent gets no hint about what 'category' scopes or how 'instructions' steers the generated Q&A.

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 (suggest) plus resource (question-and-answer pairs) for a profile, and explicitly frames the output as unsaved AI drafts. It also names the related siblings list_faqs and request_publish_faq, so an agent can place it precisely in the FAQ workflow without opening other schemas.

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

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

'Nothing is saved or published' establishes when to use this tool versus the mutating siblings, and it routes publishing to request_publish_faq and stored-FAQ reading to list_faqs. It stops short of an explicit 'do not use this when...' clause, but the alternative mapping 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?

Reinforces the readOnlyHint annotation with 'Nothing is posted' and clarifies the two-step draft-then-request flow. It doesn't clarify whether a generated draft is persisted or whether repeated calls yield different AI output (idempotentHint is false), which is the remaining behavioral unknown.

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 short sentences: purpose, safety guarantee, next step. No filler, and the key constraint is front-loaded immediately after the 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?

The tool has no output schema, and the description never says what comes back (a single suggested reply? multiple options? text only?). For a drafting tool whose whole value is the returned content, that omission leaves a real gap, though the write-safety and follow-up path are 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?

The schema declares a single required review_id with uuid format but zero description coverage; the description only implies a specific review is targeted. With only one parameter and format conveyed structurally, this is adequate but adds nothing 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?

States a specific verb and resource ('suggest replies to a review') and explicitly distinguishes itself from the sibling that performs the write ('request_review_reply'). An agent can tell draft from post without inspecting either schema.

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

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

Gives the explicit when ('suggest replies'), the when-not/outcome ('Nothing is posted'), and the named alternative for the follow-up action ('call request_review_reply'). The routing decision is fully resolved in two sentences.

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

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

Annotations already cover the read-only, idempotent, closed-world profile, so credit goes to the added context: 'as last synced from Google' discloses that results are a cached snapshot rather than live data, which is behaviorally meaningful and not in 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 front-loaded sentence whose only elaboration is the field enumeration that doubles as return-value documentation since no output schema exists. Every element earns its place.

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

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

With no output schema, the field list is essential and present, so an agent knows what it gets back. What's missing is how to supply profile_id and what happens if the profile has never been synced.

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

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

Schema description coverage is 0%, and the description never mentions profile_id at all — no guidance on where to obtain the UUID (presumably list_business_profiles). The parameter name is self-explanatory, so this is a gap rather than a failure, but the description does not compensate for the empty schema.

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

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

States a specific verb+resource ('Get a business profile's details') and enumerates the returned fields, which makes the scope unambiguous. It never explicitly contrasts with list_business_profiles or sync_profile, so sibling differentiation is left to the reader.

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

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

Usage is only implied: it retrieves a single profile by id and the phrase 'as last synced from Google' hints that data is a snapshot, but there is no explicit statement about when to call this versus list_business_profiles or sync_profile to refresh.

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 openWorldHint=false, so the safety profile is covered. The description adds domain context about what each credit type means, including that Rank Tracker credits map to map points and citation scans, but does not describe response format or rates.

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?

It is a single front-loaded sentence with no filler, and the parenthetical explanation of Rank Tracker credits is useful rather than redundant.

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

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

For a simple read-only one-parameter tool, the description covers the core resource and credit categories. However, with no output schema, it does not explain how balances are returned or whether zero/absent credits are represented, leaving a modest gap.

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

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

Schema description coverage is 0%, and the single required workspace_id parameter is only indirectly implied by 'for a workspace.' The description does not clarify the UUID format or any workspace scoping semantics beyond that phrase.

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 resource returned: current credit balances for a workspace, including Rank Tracker, analysis, and SMS credits. It is specific enough to distinguish from sibling action tools, though it does not explicitly contrast with any alternative.

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

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

It provides no guidance on when to call this tool, such as before requesting rank scans or citation scans. The intended use is inferable from the credit types, but no explicit usage conditions or alternatives are stated.

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 annotations already establish read-only, idempotent, and closed-world behavior, so the description only needs to add context beyond that. It does so meaningfully by disclosing data latency and the default date-range behavior, though it does not describe permissions, rate limits, or response structure in detail.

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 efficient sentences. It front-loads the returned metrics and then adds the latency/default-range caveat without unnecessary wording.

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

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

For a read-only metrics tool with no output schema, the description does enough by listing the metrics and totals returned and explaining the publication lag. It is slightly incomplete because it does not clarify the required `profile_id` or provide a precise response shape.

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 documents the `days` parameter, and the description adds useful context about why the range ends at the newest available day. However, schema coverage is only 50%, and the required `profile_id` parameter is not explained in the description at all.

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 resource and scope: daily Google performance metrics with an explicit list of included metrics and totals. This is clearly distinguishable from sibling tools such as review, post, rank-scan, and profile-management 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?

It gives useful usage context by explaining Google's 2-3 day publication lag and that the default range ends at the newest available day, not today. However, it does not explicitly say when to use this tool versus alternatives or name any sibling tool 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 establish read-only, idempotent, non-open-world behavior. The description adds useful return semantics, including null rank handling and the presence of coordinates and top-ranking business data, though it omits pagination or invalid-scan 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?

A single front-loaded sentence that efficiently lists the returned data and null semantics. There is no filler 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?

Given no output schema, the description does a reasonable job explaining returned fields. However, for a retrieval tool it should also clarify scan_id provenance and what happens if the scan is missing or invalid.

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 is one parameter with 0% schema description coverage. The description implies the scan identifier but does not explain the UUID format, where to obtain scan_id, or how it relates to list_rank_scans.

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 this returns point-by-point results for one Rank Tracker scan and enumerates the returned fields. It implicitly distinguishes 'one scan' from list-level tools, but does not explicitly name the sibling it differs from.

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 gives no explicit guidance on when to use this versus list_rank_scans, preview_rank_scan, or request_rank_scan. The usage is only indirectly implied by 'one Rank Tracker scan,' with no prerequisites or alternative conditions.

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

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

Annotations already cover read-only/idempotent/closed-world, so credit goes to what's added: the definition of 'interrupted' as approval started but the page closed, and the instruction to verify in GBPly before retrying. It does not mention result ordering, pagination, or what the limit bounds are, leaving some operational gaps.

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 waste: the state enumeration leads, and the parameter modes close. The parenthetical on 'interrupted' is the only elaboration and it earns its place by preventing a false retry.

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 should clarify what a call returns, and it only implies a status value per request without saying what the list mode yields or how 'limit' behaves. Adequate for selecting the tool, but incomplete for calling it confidently in list mode.

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 carry the load. It fully explains request_id (single vs omitted list mode) but never mentions the 'limit' parameter at all, leaving half the surface undocumented in both schema and prose.

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?

Specific verb+resource ('check whether requests you created were approved...') with a full enumeration of the outcome states, including the non-obvious 'interrupted' case. An agent can tell this apart from the sibling request_* tools, which create requests rather than report their status.

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 both invocation modes: 'Pass request_id for one request, or omit it to list the user's recent requests.' It also gives actionable follow-up guidance ('check GBPly before retrying') for the interrupted state. No explicit exclusion naming a sibling, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, closed-world reads, so the safety profile is covered. The description adds a genuine domain constraint the agent could not otherwise know: Google only supplies monthly granularity, and the tool defaults to the newest month with data. It omits retention window or how many months back data exists.

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 what the tool returns, followed by the key constraint and default. No filler or repetition of the tool name.

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 three params, no nested objects, and no output schema, the description covers the essential facts: what is returned, the granularity limit, and the default period. The only gap is the absence of any hint about response shape or ordering, which is minor for a simple list-returning read.

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 67%: limit and month are documented in the schema, while profile_id carries only a uuid format. The description reinforces the monthly granularity of the month parameter conceptually but adds no syntax or format detail beyond the schema's YYYY-MM pattern, 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?

The description names the concrete resource (search terms people used to find the profile on Google) and its scope (one month of data), which is clearly distinct from siblings like get_performance_insights or list_reviews. It stops short of explicitly differentiating itself from adjacent analytics tools, but the resource is 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?

It tells the agent the default behavior (newest month with data), which is useful, but gives no guidance on when to prefer this tool over get_performance_insights or other analytics siblings, and no exclusions or prerequisites. Usage is implied by the resource name only.

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 openWorldHint=false, so the safety profile is fully covered. The description adds only the fact that results include an overall score; it says nothing about result ordering, pagination behavior, or what happens when a workspace has no reports — the kind of detail the limit parameter implies matters.

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 front-loaded sentence with no filler; the resource and scope appear immediately. It is efficient but so terse that the savings come at the cost of missing parameter guidance.

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 two-parameter read tool with annotations covering safety, the definition is close to sufficient. But with no output schema and an undocumented limit parameter, the description should have said more about return shape and pagination than the single clause about overall scores.

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 carry parameter meaning and only partially does: 'in a workspace' maps to the required workspace_id. The optional limit parameter is completely undocumented in both schema and description, leaving an agent to guess its semantics and default.

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 (List) and resource (Industry Analysis / prospect reports) scoped to a workspace, plus the notable attribute that each carries an overall score. It reads clearly against siblings like list_reviews or list_workspaces, though it never contrasts itself with request_industry_analysis, which is the natural confusion point (read vs. create).

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

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

Usage is only implied by the verb 'List' — an agent can infer this retrieves existing reports rather than generating one. There is no explicit statement of when to call this instead of request_industry_analysis, nor any prerequisite or exclusion noted.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and idempotentHint=true, so safety and idempotency are covered. The description adds that results are limited to profiles 'you can access,' which is useful permission context, but it does not disclose pagination behavior or result completeness. With annotations carrying the safety profile, a 3 is appropriate.

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 with no wasted words, and the core operation plus optional filter are front-loaded. It is appropriately sized for a simple list tool.

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 low-complexity list tool with full schema coverage and read-only annotations, the description is nearly complete. It covers access scope and the optional workspace filter. The only minor gap is absence of any note about result paging or whether all profiles are returned at once, which is not critical given the simple contract.

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

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

Schema coverage is 100% and the single workspace_id parameter is already documented as 'Limit to this workspace.' The description reinforces that the limitation is optional, but adds no syntax or format details beyond the schema. Baseline 3 is correct when the schema fully documents the parameter.

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 and resource: list Google Business Profiles. It also adds the access scope 'you can access' and optional workspace filtering, making the operation clear. It does not explicitly distinguish itself from siblings like get_business_profile or list_workspaces, so it falls short of a 5.

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

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

The description implies usage for listing accessible profiles and notes the optional workspace limit, but it does not say when to prefer this tool over alternatives such as get_business_profile or list_workspaces. The guidance is adequate 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds useful domain behavior by explaining that only verified listings count toward accuracy, though it does not mention pagination, limit behavior, or authorization needs.

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

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

The description is compact and front-loaded, with no wasted wording. Both sentences provide relevant information: one identifies the resource, and the other clarifies an accuracy rule.

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 does reasonably well by naming the history metrics returned: listings found, verified, accurate, and inaccurate. However, it omits parameter semantics, especially limit, and does not clarify pagination or ordering for a history-listing 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 0%, so the description must compensate for both parameters. It implies that a profile is involved, but it does not explain profile_id or describe what limit controls, leaving meaningful 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 states the resource clearly: citation scan history for a profile, including the types of listing outcomes returned. It is specific enough to identify the tool, but it does not explicitly distinguish it from the sibling request_citation_scan 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?

There is no explicit guidance on when to use this tool versus request_citation_scan, nor any stated prerequisites or exclusions. The phrase 'scan history' implies that this is for retrieval of past scans, but that inference is 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety behavior is covered. The description adds useful context that results carry approval and publishing status and that the source of truth is GBPly, but says nothing about ordering, completeness, or whether any FAQs can be omitted (e.g. unpublished 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?

A single front-loaded sentence with the resource first and the returned status fields second; the parenthetical definition is worth its words. Slightly dense but no filler.

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

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

For a one-parameter read tool with annotations and no output schema, it covers scope and the shape of returned status data. The remaining gap is the required profile_id and whether all FAQs are returned (no pagination mention), which contrasts with sibling list_* tools that likely have similar semantics.

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

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

Schema description coverage is 0% and the description never mentions profile_id, its format, or that it is required. The only hint is the possessive 'the profile's FAQs', which implicitly ties results to a profile but gives no guidance on sourcing or validity of the identifier.

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?

Names a specific verb and resource ('List the profile's FAQs') and defines what an FAQ is here ('questions and answers kept in GBPly'), plus the extra fields returned. It is distinguishable from the write-oriented siblings (draft_faqs, request_publish_faq) through the plain 'list' verb, though it never says so explicitly.

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

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

Usage is only implied: an agent infers you call this to inspect existing FAQs and their approval/publishing status, likely before drafting or publishing. There is no explicit when-to-use, when-not-to-use, or named alternative such as draft_faqs or request_publish_faq.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds two facts beyond that: results reflect the last sync rather than live state, and ordering is newest-first. It omits pagination behavior and any indication of failure modes (invalid profile_id, empty result).

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 sentence with zero waste, front-loading the verb/resource and appending the two most decision-relevant qualifiers (sync freshness, sort order).

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 list tool with no output schema, the description covers what the tool returns at a high level and its freshness guarantee. What is missing is the pagination contract and the meaning of profile_id, both of which are absent from every structured field and force the agent to guess.

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 carries full burden for the three parameters, yet it mentions none of them. limit and offset (pagination) and profile_id (which kind of profile, what happens if it is a non-business profile) are entirely undocumented in both places.

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 photos and videos') scoped to a Google profile, plus the sort order ('newest first'). It doesn't name a sibling like list_posts or list_reviews to disambiguate the many list_* tools, but the resource is distinct enough that an agent can tell them apart.

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 phrase 'as last synced' implicitly signals that this tool does not refresh data and that sync_profile is the prerequisite for fresh results, which is a useful inference the agent can act on. However, there is no explicit when-to-use/when-not statement and no named alternative among the numerous sibling list_* 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 declare readOnlyHint/idempotentHint/openWorldHint=false, so safety is covered. The description adds genuinely useful context beyond the annotations: that Google no longer supplies per-post engagement figures, which stops an agent from probing for metrics, plus a clarification that 'pending review' means drafts awaiting approval. It stops short of describing pagination behavior or ordering.

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 tight sentences: the resource and status scope come first, and the negative information about missing engagement metrics is placed as a trailing caveat where it belongs. 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?

With no output schema and thin parameter descriptions, the definition should say more about result shape and paging (defaults, ordering, max limit). The status semantics and the no-metrics warning are the essentials and are present, but the tool is only marginally complete for a paginated list endpoint.

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 25%, so the schema alone leaves limit, offset, and profile_id bare. The description compensates for the most important parameter by explaining what each status value means (pending review = drafts awaiting approval; flagged = content policy check), but says nothing about limit/offset semantics or defaults, leaving a real 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?

States a specific verb and resource ('List Google posts for a profile') and enumerates the exact post states covered, so an agent can distinguish it from the request_*/draft_* siblings that mutate posts. No ambiguity about what is returned as a collection.

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 enumeration of statuses implies you can filter by them, and the sibling set (request_create_post, request_update_post, request_delete_post) makes clear this is the read path. However, there is no explicit 'use this when…' statement, no mention of how it relates to list_photos or list_business_profiles, and no guidance on when to page versus fetch all.

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 openWorldHint=false, so the safety profile is covered. The description adds useful content detail — that changes include edits made by Google or the public and carry old/new values — but says nothing about ordering, default limit, or pagination 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?

One tight sentence with no filler, and the resource definition is front-loaded. It is slightly dense but every clause carries information about what is returned.

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 does a reasonable job of describing returned content (old and new values, edit history). However, for a tool with three filter parameters and an undocumented limit, it leaves an agent without enough to invoke it confidently beyond the required id.

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 33%, and the description mentions no parameters at all. The required profile_id is never referenced, the limit parameter has no description anywhere, and the status filtering semantics (pending/accepted/reverted) are only partially captured by the schema example. The description does not compensate for the coverage 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?

States the specific resource — changes detected on a Google profile via Profile Guard, including edit history with old and new values. The verb is only implied by the title ('List'), but the content scope is precise enough to separate it from siblings like sync_profile or request_profile_change_decision.

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?

There is no guidance on when to use this versus alternatives — notably request_profile_change_decision, which is the action counterpart for the same Profile Guard data. The description explains what data comes back but never states when a caller should reach for this tool or what conditions exclude 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 readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered by structured data. The description does add value by disclosing that each row carries average and top-3 share summaries (useful given there is no output schema), but it says nothing about ordering, pagination, or how the limit is applied.

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 front-loaded sentence with no filler; scope, filter dimensions, and returned summaries are all packed into it 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?

For a read-only list tool with three parameters, zero schema documentation and no output schema, the description covers intent and return shape but leaves the limit/pagination contract and result ordering unexplained. Adequate to attempt a call, not complete enough to call confidently with non-default paging.

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 carry parameter meaning, but it never mentions the `limit` parameter at all. The parenthetical "(keyword, grid size, date)" plausibly describes scan attributes rather than inputs, since no grid-size or date parameter exists, which risks misleading the agent about what it can filter on.

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?

Names a specific verb+resource ("List Rank Tracker grid scans") and scopes it to a profile with the dimensions carried (keyword, grid size, date) plus the summary metrics returned. It does not explicitly distinguish itself from the sibling get_rank_scan (single scan) or list_citation_scans, so sibling differentiation is only implicit.

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?

There is no guidance on when to use this versus get_rank_scan for a single scan or request_rank_scan to kick off a new one, and no prerequisites or exclusions are stated. The only hint is that listing is per-profile, which the required profile_id already conveys.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: default sort order (newest first) and the nuanced definition of 'needs_attention' as pending, rejected, or delisted by Google. It stops short of describing pagination behavior or how the rating stats are aggregated.

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 zero filler: the core operation and ordering come first, the filter modes second, the side-payload last. Every clause carries information an agent would otherwise have to infer.

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 5-parameter read tool with no output schema and thin schema coverage, the description covers purpose, ordering, filter semantics, and the bonus return of overall rating stats. What is missing is pagination guidance (offset/limit interplay) and a hint at the shape of a returned review, which leaves a small gap.

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

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

Schema description coverage is only 20% (just limit), so the description has to carry the weight and largely does: it defines all three `filter` enum values semantically and explains that filtering can also happen 'by star rating'. The `offset` and `profile_id` parameters remain unexplained in both places.

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 a profile') plus the ordering ('newest first') and the payload ('with reply status'). No sibling tool lists reviews, so the scope alone is enough to separate it from draft_review_reply and request_review_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?

The description explains what each filter mode selects ('unanswered', 'reviews needing attention (reply pending, rejected or no longer shown by Google)'), which implies when to pick each. However, it never says when to use this tool versus the reply-oriented siblings, and gives no explicit exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered. The description still adds value by disclosing what is returned (your role per workspace, AI connector enablement), which an agent cannot get from the annotations; it simply stops short of noting ordering or authentication requirements.

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?

One sentence that front-loads the action and resource, then the return content. No filler, no redundancy with the title.

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

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

With no parameters and no output schema, the description carries the return-value burden and does name the key fields returned. It is nearly complete for such a simple tool, though a brief note on how role/enablement affect subsequent tool calls would close the last gap.

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

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

The tool takes zero parameters, so per the baseline there is nothing for the description to clarify beyond what the empty schema already conveys. No parameter-related gaps exist.

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 the GBPly workspaces you belong to') and previews the returned fields (role, AI connector status). It does not explicitly differentiate from the sibling list_business_profiles, so an agent must infer the hierarchy from names alone, but the purpose itself is 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?

Usage is only implied — as the natural entry point for discovering which workspaces the caller can act in. There is no explicit statement of when to call this versus list_business_profiles or any other sibling, and no prerequisites or exclusions are given.

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 readOnly/idempotent/closed-world, and the description adds real value on top: the billing model (one credit per map point), the grid bounds, and an explicit non-execution guarantee. It omits what happens with insufficient balance or whether the profile must exist, which are the remaining behavioral unknowns.

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 waste; the cost-and-balance payload is front-loaded and the non-execution caveat follows immediately.

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?

There is no output schema, and the description does name the two things returned (credit cost and workspace balance), which is sufficient for a read-only preview. The gap is profile_id semantics and error/insufficient-credit behavior.

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

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

Schema coverage is 0%, so the description carries the full burden of explaining all three parameters. It usefully converts grid_rows/grid_cols into a cost formula ('one per map point') and bounds, but profile_id — a required UUID that determines which workspace is billed — is never explained.

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 (Show) and resource (Rank Tracker scan cost plus workspace balance), and scopes it to a 3x3–12x12 grid. The final sentence 'Does not run anything' cleanly separates it from the request_rank_scan sibling without needing 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?

The 'Does not run anything' clause implies a preview-before-request use case, which is clear guidance for an agent. It stops short of naming request_rank_scan as the follow-up action or stating when this preview should be skipped, so it lacks explicit alternatives.

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

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

The description adds context the annotations do not carry: the operation costs Rank Tracker credits at the current scan price, is only charged after approval, and returns an approval link. This reconciles well with destructiveHint=true and non-idempotent (a billable, user-gated action), and no contradiction exists. Only missing piece is what happens if approval is declined or stale.

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?

One sentence plus a clarifying parenthetical; the action and the human-approval requirement are front-loaded, and every clause (cost, exclusion, return value) carries information an agent needs.

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 annotations covering the safety profile and no output schema, the description supplies exactly the missing pieces: cost model, approval gating, and return value. Only the profile_id semantics is left implicit, which is minor for a one-parameter tool.

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

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

The single parameter profile_id has 0% schema description coverage, and the description never mentions it or says which business profile the scan applies to. The field name is largely self-explanatory (a UUID for a profile, with list_business_profiles available), so the gap is tolerable but unaddressed.

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: request user approval for a Citation Management scan of the business's directory listings. The parenthetical exclusion ('does not create or submit listings') sharpens the scope, though it doesn't explicitly name the sibling list_citation_scans or the other request_* tools it precedes.

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?

'Ask the user to approve' makes the human-in-the-loop precondition explicit, and the credit-charge note tells the agent this is a billable step to be used deliberately rather than speculatively. No explicit when-not-to-use condition or named alternative is given, so it falls just short of a 5.

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

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

Annotations already flag destructiveHint=true and non-idempotence, but the description earns its keep by explaining the actual behavior: it returns an approval link, the org's policy check and daily post cap still run, and rejected posts are kept as flagged rather than published. That tells the agent the write is deferred and may silently not go live, which annotations alone cannot convey. It does not cover retry/duplicate behavior for a non-idempotent call.

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

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

Three short sentences with the action and outcome up front, then the scheduling detail, then the policy caveat. Every clause carries information an agent would otherwise have to guess at.

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 approval flow and policy behavior are well covered, and there is no output schema to explain. But for a 15-parameter tool with two enums and internal conditional requirements, the description leaves the agent without guidance on which fields are mandatory for OFFER/EVENT posts or how the button fields relate.

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 15 parameters and only 33% schema description coverage, the description must carry conditional semantics and it largely doesn't; it only adds that scheduled_at is ISO 8601. It never explains that event_*/coupon_code/terms_conditions are tied to post_type EVENT/OFFER, or that cta_url is required except for CALL — the highest-risk mistakes an agent could make here.

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?

It states a specific verb and resource ('Ask the user to approve a new Google Business Profile post') and scopes it to creation of a new post, published immediately or scheduled. The approval-request framing cleanly separates it from the draft_* and request_update_post siblings, which is exactly the distinction an agent needs before picking a 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?

It makes clear the tool is for approval-gated publishing and explains both modes ('published now or scheduled'), including the parameter that selects scheduling. It stops short of naming alternatives (list_posts, request_update_post, request_delete_post) or stating exclusions, so it is clear context without explicit 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?

Annotations already declare destructiveHint=true and non-idempotent, but the description adds the crucial nuance that this is a gated, approval-mediated flow ('Ask the user to approve', 'Returns an approval link') rather than an immediate delete — context the flags alone cannot convey. It stops short of stating approval-link lifetime, what happens if the post_id is invalid or already live, or the outcome for the requester.

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 short sentences, zero filler: eligibility first, exclusion second, return value last. Every clause carries operational information.

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

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

For a one-parameter, no-output-schema tool the description covers purpose, eligibility, exclusion, and the return value ('Returns an approval link'), which is enough to call it correctly. The only missing piece an agent might want is how to source the post_id and whether the approval is async/pollable via get_request_status.

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 post_id is described as a UUID in the schema but has 0% description coverage, and the description never explains it — not how to obtain the ID (presumably from list_posts) nor that it must reference a post in one of the eligible states. With only one param this is a minor but real gap, landing at 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?

States a specific verb ('Ask the user to approve deleting') plus the resource ('post from GBPly') and enumerates the exact states that qualify (scheduled, draft, pending-review, flagged, failed). It is clearly distinguishable from sibling write tools like request_create_post, request_update_post and from the read-side list_posts.

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 both the when ('scheduled, draft, pending-review, flagged or failed post') and the explicit when-not with alternatives ('Posts already live on Google can't be deleted through the connector; remove those in GBPly or Google'). An agent knows both the qualifying filter and the escape hatch without inferring anything.

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 flag destructiveHint=true, but the description materially changes how an agent should act on that by disclosing the effect is deferred and gated on human approval, and that an approval link is returned. It does not cover retry/idempotency behavior (idempotentHint=false) or whether the pending request expires, which would have completed the picture.

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 filler, with the approval-gating constraint front-loaded right after the action statement. Nothing to trim.

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 one-parameter tool with no output schema, the description conveys the essential mechanics: what it does, that it returns a link, and that no state changes yet. The remaining gap is the handoff — where review_id comes from and that get_request_status is how the approval outcome is observed.

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% for the single parameter, and the description says nothing about review_id — not its expected UUID format, not that it comes from list_reviews, not whether it identifies a reply or its parent review. The one parameter an agent must supply is left entirely to the bare schema.

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

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

States a specific verb-and-resource pair: request approval to delete the business's reply to a Google review. This is clearly separable from request_review_reply (drafting/publishing) and request_delete_post, and it names the exact artifact being deleted.

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?

'Ask the user to approve deleting...' plus 'nothing changes until approved' establishes the approval-flow context in which this tool belongs. It stops short of routing explicitly to siblings like request_review_reply (to modify instead) or get_request_status (to check the outcome), so an agent must infer those.

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 annotations already declare destructiveHint=true, openWorldHint=true, and non-idempotent, but the description adds crucial context the annotations can't: it requires user approval, consumes one analysis credit, returns an approval link, and results appear asynchronously in GBPly and list_analysis_reports. It doesn't restate what 'destructive' destroys beyond the credit note, keeping it just shy of 5.

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 front-loaded sentence packed with purpose, example, cost, and return path. Every clause earns its place, with no filler.

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

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

With no output schema, the description carries the return explanation ('Returns an approval link') and the async result location, which is complete for a request-style tool. The only gap is the undocumented workspace_id required param.

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 schema documents none of the three params. The description supplies example values for query ('dentist') and location ('Leeds'), which aids semantics for two params, but workspace_id is left entirely unexplained.

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 ('Ask the user to approve an Industry Analysis search') with a concrete example of query and location, so the agent can tell it apart from request_rank_scan and request_citation_scan. It also names the sibling where results surface (list_analysis_reports).

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 approval flow and credit cost imply when to call it, and the mention of list_analysis_reports gives a routing hint for viewing results. However, it doesn't explicitly say when to use this versus alternatives like get_request_status or list_analysis_reports, leaving the agent to infer.

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, openWorldHint=true and non-idempotent, so the safety profile is covered; the description adds genuine value by spelling out what each decision does to the remote value and by disclosing that the call returns an approval link rather than applying the change immediately. It still doesn't say what state the change sits in after the approval link is issued or whether the revert is recoverable.

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 front-loaded sentence plus one short return-value sentence; the scoping prerequisite comes first and every clause carries distinct information.

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

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

For a destructive, open-world mutation with no output schema, the description covers the action semantics and the approval-link return, which is the critical piece. It omits the follow-up path (e.g., whether to poll get_request_status after approval) and any permission/auth requirements, leaving a meaningful gap.

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

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

Schema coverage is 0%, so the description must carry the burden. It defines 'accept' (keep Google's new value) and 'revert' (restore the previous value) well, but leaves 'dismiss' undefined and only implies that change_id comes from list_profile_changes — enough to be usable, not enough to remove all ambiguity.

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?

It names the specific verb (accept/dismiss/revert) and the specific resource (a pending change from list_profile_changes), and defines each option's effect on the underlying Google value. An agent can distinguish this from sibling mutation tools like request_profile_update without opening a schema.

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

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

It explicitly scopes usage to 'a pending change from list_profile_changes', which tells the agent both the prerequisite and the source of the change_id. It does not state when not to use it or how it differs from request_profile_update/sync_profile, so it falls short of a 5.

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

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

With annotations already declaring destructiveHint=true, openWorldHint=true and idempotentHint=false, the description adds real context the agent couldn't otherwise know: the call does not apply the change directly, it returns an approval link requiring human action, and Google may still review the edit afterward. It doesn't state that the new value overwrites the existing field or what happens if a prior request is pending, which is the remaining gap for a destructive mutation.

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

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

Three sentences, front-loaded with the action and constraint, then the parameter-shape hint, then the return/risk note. No sentence restates the name or title and nothing could be removed without losing information.

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

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

For a 3-parameter destructive open-world tool with no output schema, the description covers the approval flow, the value shape source, the return artifact, and external review risk. It is nearly complete; only overwrite semantics, pending-request behavior, and approval-link lifetime are left unstated.

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% and the 'value' parameter is an untyped empty object, so the description carries the burden and does well: it maps value shape to each enum field (text for description/phone/website; arrays/objects for hours, special hours, services, categories) and tells the agent to mirror get_business_profile's output. It still leaves the internal structure of the array/object fields unspecified, and says nothing about profile_id beyond it being required.

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 ('Ask the user to approve changing one profile field on Google') and bounds scope to a single field. An agent can distinguish this from list_profile_changes and request_profile_change_decision without opening either schema, because it makes clear this initiates the edit rather than reading or deciding on one.

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

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

Gives clear context for when to call it (requesting a user-approved change to one field) and points to get_business_profile as the source of the correct value shape. It does not name explicit exclusions or alternatives (e.g. when to use request_profile_change_decision instead, or that multi-field edits require separate calls), 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?

Goes beyond the annotations by disclosing that this is an approval-request flow rather than an immediate publish, and that it returns an approval link — exactly the kind of flow context annotations cannot express. It stops short of saying what the approval ultimately makes public or what happens post-approval, but the core behavior is well surfaced.

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 tight sentences, with the core action leading and the return value trailing. The GBPly Q&A Manager analogy is a minor cost but earns its place as a mental model.

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?

Returns are covered ('approval link') despite no output schema, and the approval-flow nature is clear for a mutation tool. But the meaning of image_url, the effect of scheduled_at, and the consequence of eventual publication (relevant given destructiveHint=true) are left unstated.

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

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

With 0% schema description coverage, the description must do the work: it explains that faq_id refers to a saved FAQ from list_faqs and that 'publishing (or scheduling)' maps to scheduled_at. However, image_url is never addressed anywhere, so one of three parameters remains unexplained.

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: publishing/scheduling a saved FAQ as a Google post, and anchors the resource to list_faqs so the agent knows the source. It does not distinguish itself from the closely related request_create_post sibling, which also produces a post, leaving some ambiguity about which to pick.

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 phrase 'Ask the user to approve' implies this is the approval-gated path rather than a direct create, and referencing list_faqs implies the FAQ must already be saved. But it never explicitly contrasts with request_create_post or states exclusions/prerequisites, so usage is only implied.

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, openWorldHint=true and non-idempotent, so the bar is lower. The description nonetheless adds material context the annotations cannot express: the credit cost model (one credit per map point), the fact that credits are charged only after approval, and that the call returns an approval link rather than running anything immediately. It does not cover what happens on rejection or link expiry.

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, no filler, with the approval/payment gate front-loaded before the return value. Every clause carries information an agent needs.

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 does the right thing by naming the return value (an approval link) and the cost semantics. But for a 5-parameter, paid, destructive-tagged operation it leaves the grid dimensions — the main driver of both cost and scan shape — undocumented, which is a real gap.

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

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

Schema description coverage is only 20% — just spacing_km. The description explains the keyword and the business-centring (profile_id), but grid_rows and grid_cols, which directly determine the credit cost, are left entirely unexplained in both schema and description. With low coverage the description needed to compensate and 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?

A specific verb (request/ask the user to approve) applied to a specific resource (a paid Rank Tracker scan), scoped to a keyword centred on the business. The parenthetical pointing at preview_rank_scan signals the distinction from that sibling, though it is framed as a cost reference rather than a purpose contrast.

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

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

The description implies the trigger (the user wants a paid scan for a keyword) and points to preview_rank_scan for cost. But it never says when not to use this tool, nor directs the agent to list_rank_scans/get_rank_scan to retrieve results after approval, or to get_credit_balances before committing.

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 real context beyond the annotations: it returns an approval link, nothing is posted until the user approves, execution may run immediately under an Always-allow setting, and policy checks still apply. It does not cover what happens on rejection or how a replacement interacts with the existing reply, which the destructiveHint=true annotation implies is relevant.

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 compact sentences, front-loaded with the action and the approval gate, then the exception and the policy caveat. No filler.

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

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

For a two-parameter mutation with annotations and no output schema, the description covers the human-in-the-loop flow, the bypass path, and the policy constraint well. The remaining gap is parameter meaning and character-limit guidance, which the schema fails to supply.

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 needed to carry the parameter burden and does not. Neither review_id (UUID format) nor reply_text (1-4000 chars) is mentioned or constrained anywhere in the prose.

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: asking the user to approve posting or replacing a reply to a Google review, which is clearly distinct from the delete/reply-drafting siblings by name. It never explicitly names draft_review_reply as the companion tool, so the differentiation is implied rather than spelled out.

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

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

Usage is implied rather than stated: this is the approval-gated posting path, and the 'Always allow' note hints at a faster path when permission is pre-granted. There is no explicit guidance on when to call it versus draft_review_reply first, nor any exclusion criteria.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true; the description earns credit for adding that an approval link is returned and that GBPly's post policy check still applies, which explains why the call is not immediately effective. It does not say what happens to fields omitted from the new content or how the approval is later tracked (e.g. get_request_status).

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 short sentences, front-loaded with the action, then the payload rule, then the return value and policy caveat. No filler.

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

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

For a 14-parameter, non-idempotent mutation with no output schema and low schema coverage, the description covers the core contract (full content, approval link, policy check) but is thin on the many event/offer-specific fields and on how the pending request is later polled or resolved.

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 36% across 14 parameters, so the description must compensate. Beyond 'send the full new content' it says nothing about post_type, cta_type/cta_url pairing, coupon_code, terms_conditions or the event_* fields, leaving most of the parameter surface undocumented.

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 ('ask the user to approve changes to an existing post') and scopes it to published, scheduled or draft posts. This cleanly separates it from siblings request_create_post and request_delete_post without needing to name them.

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 phrase 'changes to an existing post' clearly establishes the edit-existing use case, and 'Send the full new content' tells the agent to supply a complete replacement rather than a delta. It stops short of explicitly naming request_create_post/request_delete_post as the alternatives or stating when not to use it, so a 4 rather than 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?

The description adds a genuine behavioral fact not in annotations: a rate limit of a few syncs per hour. Annotations already cover idempotency, open-world and non-destructive write semantics. What remains undisclosed is whether the sync is synchronous or long-running (relevant given the get_request_status sibling) and what a repeat call does.

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 short sentences, zero filler, with the operation and its data source front-loaded before the rate-limit caveat.

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

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

For a single-parameter tool with no output schema this is nearly adequate, but an agent still lacks the two things that matter most: whether the call returns immediately or must be polled, and how to source the profile_id.

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

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

Schema description coverage is 0% and the description never mentions profile_id — not its format (uuid), not where to obtain it (list_business_profiles). The parameter name is self-explanatory, so this is a modest gap, but the description does nothing to compensate for the empty 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 states a specific verb and resource (refresh a profile's details and reviews from Google) and clarifies the operation is a pull-from-Google sync, which distinguishes it from the mutation sibling request_profile_update. It does not explicitly name that sibling, but the direction of data flow is clear.

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

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

The parenthetical "the same as Sync in GBPly" anchors the behavior for product-familiar users, and the rate-limit sentence implies this is a scarce, occasional operation. However there is no explicit when-to-use vs. request_profile_update, nor guidance on whether to poll get_request_status afterwards.

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