Is it legit? Reviews trust checker

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

Goes well past the annotations (which only say non-readonly, non-idempotent, non-destructive) by disclosing that the URL is a bearer-style secret completing the submission under the caller's identity, that no key is needed on the POST, and that the HTTP response is the trust report. It also adds lifecycle semantics the annotations cannot express: 2-hour expiry and supersede-on-one-shot 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?

Four sentences, all substantive, with the core outcome (reserves + returns upload_url) front-loaded before the identity caveat and the alternative path. Slightly dense — the identity warning and the expiry note each carry a lot of compressed meaning — but nothing is 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 tool with no output schema, the description still explains what comes back (upload_url from the call, trust report from the POST) and how the submission terminates. The identity, key, and expiration semantics cover everything an agent needs to invoke it without breaking the flow.

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 80%, so place_id, url, agent and expected_reviews are already documented in the schema and the description mostly restates the payload/agent-identity idea. It does introduce submission_id, which is not an input parameter here, so it adds routing context rather than parameter meaning; baseline 3 fits.

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?

Opens with a specific verb and resource — 'Reserves a submission and returns an upload_url' — so the agent knows both the side effect and the return value immediately. It is clearly separable from siblings: submit_reviews is named as the chunked alternative and finalize_submission is implicitly the other end of the lifecycle.

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 explicit routing conditions: use this when you can POST the full JSON payload from your own environment or the user's browser, and use submit_reviews instead when feeding submission_id in inline chunks. It also points to describe_review_source for payload format, leaving no ambiguity about which tool to reach for.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavior: it reports cache freshness and an actionable recommendation, and 'Never contacts Google' clarifies that resolution is local even though the input is a Google Maps URL — a real concern the annotations only hint at.

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

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

Front-loaded with the imperative 'Call first,' then the capability, then the recommendation branches. Dense and nearly waste-free; the parenthetical about corroboration is slightly compressed but still earns its place by altering the recommended action.

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

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

There is no output schema, and the description compensates by explaining what is returned: cache existence, freshness, and a recommendation. Combined with the fully documented parameters, an agent has what it needs to call this correctly; only the zero-argument case is left unspecified.

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

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

Schema coverage is 100%, so both url and place_id are already documented in the schema, including the short-link caveat. The description repeats the 'link or place_id' framing without adding format or precedence details. Notably it does not say what happens when neither argument is supplied even though none are required, leaving that ambiguity 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: resolves a Google Maps link or place_id and reports cache status, freshness, and a recommended next action. This is clearly distinguishable from siblings like get_place_trust (which presumably returns the trust result itself) and list_scored_places (which enumerates).

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 opening 'Call first' gives explicit ordering guidance, and the description routes the agent to one of two follow-ups: use the cached result or collect/submit reviews. It also carves out the corroboration case for single-source cached results. It stops short of naming which sibling to call for each branch, so the mapping is inferred rather than 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?

Annotations already declare this a safe, idempotent read, so the description correctly spends its budget on content instead: it enumerates the returned contract (required vs optional fields, where each lives on the page, example payload, delivery instructions). It also discloses a real constraint the agent would otherwise trip on — everything required is visible on the review card — plus the sort-by-newest and 500-most-recent rules.

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 directive "Read this BEFORE scraping" is front-loaded where the agent will see it, and every clause carries distinct information. The middle section is a long comma-chained list that is dense but not padded; it could be broken into shorter sentences for scanning.

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

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

No output schema exists, so the description carries the return-value burden itself and does so by enumerating the fields, rules, examples, and delivery format it provides. For a one-optional-param discovery tool, nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the enum already constrains the value, so the baseline is 3. The description adds meaning beyond it by explaining what omitting the parameter does (lists supported platforms) and that only Google Maps currently exists, which prevents the agent from assuming multi-platform coverage.

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

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

The description uses a specific verb-plus-resource framing — it returns, per platform, the exact submission format including identity fields, per-review fields, source locations, and an example payload. An agent immediately knows this is a schema/spec-discovery tool rather than a data-fetching or submission tool, which distinguishes it from siblings like submit_reviews and begin_submission.

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?

"Read this BEFORE scraping" gives an explicit ordering constraint, and the no-platform branch is described as a listing mode. What is missing is naming the actual workflow alternatives (submit_reviews, begin_submission) and stating that this tool must be called instead of guessing a payload. Clear context, but no explicit exclusions.

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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing the stored-report short-circuit (explaining the idempotency) and the 'pending with nothing uploaded' outcome, but it omits cost/latency expectations, error conditions beyond pending, and what 'says so' actually returns.

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

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

Three tight, parallel sentences that front-load the most common case and use zero filler. The telegraphic phrasing ('says so') costs a little precision but nothing is wasted.

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, so the description is the only place to explain what the returned 'report' contains, and it does not. For a single-parameter, non-destructive, idempotent call the state coverage is decent, but the return shape and the submission_id source remain unexplained.

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 required parameter, submission_id, so the description must carry the burden of explaining it and does not — no format, source, or origin is given. It mentions 'upload_url' and 'inline chunks' only as submission states, not as parameter guidance, leaving the one input 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?

The description enumerates three concrete state-dependent outcomes (inline-chunk submission gets validated/scored/stored and returns a report; uploaded submission returns the stored report; empty pending submission returns a status message), which makes the tool's function unmistakable. It falls short of 5 because it never names a sibling or explicitly frames this as the 'finalize' step relative to begin_submission.

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 state-based enumeration implicitly tells the agent which scenario it is in, which is useful routing guidance. However there is no explicit prerequisite statement (e.g. that begin_submission must have run first) and no exclusion or named alternative, so the guidance is implied rather than 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's marginal value is the cache-miss behavior, which it discloses plainly. It adds no auth, rate-limit, or staleness/TTL detail for a cache-backed tool, which is the main remaining gap.

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

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

Front-loaded with the purpose, then a dense enumeration of return fields, then the cache constraint. The field list is long but justified because there is no output schema; the single-sentence run-on is the only structural weakness.

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 heavy lifting by listing the returned artifacts (verdict, grade, trust score, adjusted rating, injection stats, duplicates, red flags, provenance), which is enough to decide whether to call it. Some items like 'reviewer-mix tiers' remain underspecified in shape, and cache-expiry behavior is 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 100% and the url/place_id descriptions already explain the formats and that short-links cannot be resolved, so the description need not repeat them. It contributes nothing parameter-specific beyond 'a place', which is the expected baseline when the schema does the work.

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: it returns the cached fraud analysis for a place, and it enumerates the verdict taxonomy (looks_legit / not_sure / past_manipulation / inflated / manipulated). The 'Cache only' clause plus the check_place pointer cleanly separates it from the sibling check_place pipeline.

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 names the alternative and the condition that selects it: use this for cached lookups, and on a miss 'collect and submit the reviews (see check_place)'. An agent knows exactly what to do on an empty result without guessing.

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 safety profile (readOnly, idempotent, non-destructive), so the description's job is added context — it delivers the sort order (best adjusted rating first), the fixed page size of 25, and that the response echoes available cities/lists with counts. It does not describe pagination limits or what happens past the last page.

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

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

Two dense sentences with the ordering and pagination facts front-loaded, then filters and response contents. No filler or restated title language.

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 burden of explaining returns, and it covers the ranking, page size, and the cities/lists-with-counts metadata. It leaves the shape of individual place entries unspecified, a minor gap for a browse tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value by noting the page size of 25 (not in the schema) and by tying the city slug to the `cities` field of a prior response, which tells the agent how to discover valid filter values.

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 resource ('the ranked directory of places already analyzed for review fraud') plus the ordering rule and page size, which is enough to separate it from the single-place siblings like check_place and get_place_trust.

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 this is the right tool ('what the site's home and city pages show') and signals discovery usage by noting the response lists available cities/lists with counts. It stops short of naming an alternative for the single-place case or stating when not to use it.

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

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

Annotations only declare a non-read-only, non-destructive, non-idempotent write; the description adds the real behavioral contract: chunk protocol, that final=true must ride the last chunk, that identity fields may arrive with any chunk, and that the trust report is returned once finalized. It stops short of saying what happens on rejected/duplicate chunks or invalid review rows, which matters given idempotentHint=false.

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

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

Front-loaded with the one-shot case first, then the escalation path, then the exclusivity caveat, then the return value — a sensible order for an agent deciding which route to take. The justification clause about retyping is a slightly long aside, but it earns its place by reinforcing the usage constraint.

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 19-parameter, zero-required, no-output-schema ingestion tool, the description covers mode selection, batching limits, correlation keys, and the return value ('the trust report when finalized'). Combined with 68% schema coverage, an agent has enough to call it correctly; remaining gaps are field-level validation details rather than call-shaping information.

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 68%, so many fields are documented structurally, but the description still adds meaning the schema cannot: the role of submission_id as the chunk-correlation key, and the fact that identity fields are chunk-order-independent. It says nothing about how lat/lon/name/address relate to placeId/cid resolution, leaving that inference to the agent.

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

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

States a specific verb and resource ('Submit the review feed inside the tool call') and immediately splits it into two modes: a one-shot whole-payload submission and a chunked flow that depends on begin_submission. That split lets an agent tell this tool apart from begin_submission/finalize_submission without opening a single 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?

Explicit when-to-use ('only when you cannot POST to the upload_url yourself (no page fetch, no curl)'), explicit alternative, and explicit thresholds ('fine up to about 150 reviews', chunks of up to 150). The exclusion is backed with a reason (retyping is slow and error-prone), so the agent knows why the other route is preferred.

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