Geocode AI

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

Rich disclosure beyond the annotations: notification side effects (you receive status emails, the author gets a daily digest), cost (free), rate limit (50 comments/account/day), auth requirement, and visibility model (feature requests public without author email, issues private to you and the team), plus a data-handling warning. It does not explain why destructiveHint=true is set — nothing states whether comments can be edited or deleted or whether posting is irreversible — which is the one behavioral 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 core action and the preferred-alternative routing, then dense factual sentences on side effects, limits, visibility and safety. It is telegraphic and slightly packed, but nearly every clause carries decision-relevant 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?

Only two parameters, 100% schema coverage, no output schema needed, and annotations cover the safety profile. The description still supplies everything an agent needs — auth, quota, visibility, notification consequences and a PII/secret-handling warning — so nothing material 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%, so the baseline is 3; the description earns a step up by telling the agent what to put in the body (use case, failing request id, workaround), which the schema's "The comment." does not. The id source is already covered by 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?

"Adds context to an existing feature request or issue: your use case, another failing request id, a workaround" gives a specific verb (adds context/comment) plus the exact resource and even the content types expected. It is clearly separable from request_feature, report_issue and upvote_feedback.

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 preferred workflow ("Prefer it (with upvote_feedback) over filing a near-duplicate") and implicitly excludes create-type siblings by requiring an existing item id. An agent knows when to pick this instead of filing new feedback.

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 well beyond the annotations by disclosing the 10,000-point cap, the billing cost of 1 unit per 1,000 points, and the auth requirement (API key or connected account). Annotations only cover safety and idempotency, so cost and credential prerequisites are genuinely new and decision-relevant information.

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 with the core behavior, the use cases, and the operational constraints in that order. No filler, no restatement of the title, and the cost/auth caveats come before the agent commits to a call.

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 only two parameters and no output schema, the description still covers return shape (boolean per point plus inside count), input limits, pricing, and authentication. There is no material gap an agent would need to guess at before calling.

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

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

Schema description coverage is 100% and the parameter-level descriptions already spell out the boundary id formats and the [lon, lat] GeoJSON ordering, so the schema does the heavy lifting. The description adds only the point-count ceiling and the 'one boundary per call' constraint, so baseline 3 applies.

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

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

States a precise verb and resource: testing up to 10,000 [lon, lat] points against a single boundary, with both the boolean-per-point result and the inside count named. It is clear enough to separate from generic boundary tools, but it never distinguishes itself from reverse_boundaries, which is the obvious alternative for point-in-boundary style lookups in this toolset.

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 concrete usage contexts (geofencing, service-area checks, filtering customer lists) so an agent knows the class of problem this solves. It stops short of exclusions or naming a sibling to use instead, which keeps it out of 5 territory.

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 give the generic hints (not read-only, not destructive, not idempotent). The description adds genuinely non-obvious behavior: the secret is shown once and cannot be retrieved again, the key inherits the creator's role capped at admin, and it survives the creator's departure until an admin revokes it. That is exactly the context an agent needs before invoking a credential-minting tool.

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

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

Four tight sentences, front-loaded with the action and its irreversible consequence, then the environment-variable advice, then scope/role, then auth. No filler and no repetition of 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?

For a single-parameter, non-idempotent creation tool with no output schema, the description covers the return value (the secret, delivered once), the security implication, the authorization model, and authentication requirements. Nothing material 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?

There is a single optional parameter with 100% schema description coverage and a documented default, so the schema already carries the semantics. The description adds nothing about the name field, which is acceptable but not additive.

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 (creates an API key) and scopes it to the organization, plus names the distinguishing behavioral trait that the secret is returned only once. An agent can tell this apart from list_api_keys or revoke_api_key from the description alone.

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 states a prerequisite ('Needs an API key or a connected account') and the lifecycle context, which implies when creation is appropriate, but it never explicitly routes the agent to alternatives or says when not to create a key. Usage is implied rather than prescribed.

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 substantial context beyond the annotations: the agentic planning over real administrative boundaries, the return shape (GeoJSON plus per-part sources), the 422 failure mode explaining unmapped text, latency of 30 s to minutes, and an auth requirement (API key or connected account). The one gap is that 'create' implies a persisted resource, but the description never says whether the area is stored in an account, retrievable later, or reusable — relevant since readOnlyHint is 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?

Four sentences, front-loaded with the core transformation, then output, then latency, then the routing alternative and auth. Each sentence carries distinct decision-relevant information with no repetition of the title or schema.

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 compensates by naming the return format and error case. Combined with latency, auth, and the alternative path, an agent has everything needed to decide and call correctly for a slow, open-world, non-idempotent generation tool.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the seed point constraint and country code. The description only reinforces the meaning of `text` via an inline example; it adds nothing about seed semantics, the source field, or how country scopes the mapping. Baseline 3 is appropriate.

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

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

States a specific transformation (plain-language description → one validated land-only polygon) with a concrete example input, and explicitly contrasts itself with search_boundaries + get_boundary for simple lookups. An agent can distinguish this from every sibling without opening the schema.

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

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

Gives an explicit alternative and the condition that selects it ('For a single named place use search_boundaries + get_boundary instead'), even quantifying the tradeoff as instant and 1 unit versus minutes here. Also states the input sources it accepts (free prose, contract or policy wording), which frames when this tool is the right choice.

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

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

Annotations declare openWorldHint=true and destructiveHint=false, but the description adds substantial context: the call is free and charges nothing, card details must never be passed to a tool, behavior differs with and without a key (guest_checkout creates the account on payment), and paid-plan links are prorated switch confirmations. That is a rich behavioral profile beyond what the annotations state.

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?

Purpose is front-loaded in the first sentence and every sentence carries operational instruction rather than filler. However, it is a dense single block with long run-on clauses and some repetition (the Stripe/Geocode AI branding is restated), so readability suffers slightly.

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 tool with no output schema, the description covers everything an agent needs: what the return value is (a url), how to hand it over, what to tell the human (plan and price), the no-key guest flow, and the follow-up call to verify payment. Nothing essential 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%, so both parameters are already documented. The description still adds agent-facing meaning: monthly is the default and yearly: true bills ten months' price once a year, plus the prorated-switch context for existing paid plans. Modest but genuine value over 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 — creates a link a human opens to buy a plan (pro or business) via a Stripe checkout page. It clearly separates this from get_pricing (prices/limits) and get_account (payment status), so an agent can tell it apart from all siblings 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?

Explicit conditions and exclusions: 'only call it when the human asked to buy or upgrade', 'Never open or pay it yourself', 'Give the url to the human as is'. It also routes to alternatives and follow-ups — get_pricing for prices, get_account to check when it is paid.

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

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

Beyond destructiveHint/idempotentHint, it discloses the cascade (shares are also removed), the permission requirement (admin access on the file), the auth model, and that the underlying exported file is NOT deleted from the public cache. That last point is non-obvious behavior an agent could otherwise get wrong.

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 destructive scope, followed by the side-effect caveat and then cost/auth. The one-word 'Free.' is slightly clipped but carries useful information and costs nothing in length.

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 destructive tool with annotations already declaring the safety profile, the description covers cascade, permissions, auth, cost, and the cache-side effect. The only unaddressed item is reversibility/restore, which is a minor gap given the annotations.

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

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

Schema description coverage is 100% and the single id parameter is already documented with its source (list_files or save_file). The description adds no further meaning about the identifier, so baseline 3 applies.

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

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

States a specific verb and resource ('Removes a file from the organization's library') plus the cascade effect ('and its shares'), which implicitly separates it from unshare_file. It stops short of explicitly naming an alternative sibling, so it's clear but not fully differentiated.

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

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

Gives real preconditions — admin access on the file, an API key or connected account, and that it's free — and preempts a common worry by noting the exported file stays in the public cache and export_boundary can rebuild the url. No explicit when-not-to-use or named alternative, so not 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?

Goes well beyond the annotations: it discloses cost (1 unit), the auth requirement (API key or connected account), output permanence and CDN caching/sharing, and that the REST route redirects. Those are exactly the operational facts annotations cannot express. There is a mild tension with idempotentHint=false, since 'built once and then shared' implies repeat calls resolve to the same file, but this describes file construction rather than the operation result, so it is not a contradiction.

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

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

Effectively two sentences: the first front-loads what is produced and returned, the second covers use cases, cost, sharing and auth. No filler, and the most decision-relevant facts (formats, detail, URL) lead.

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 still tells the agent exactly what comes back (a permanent public CDN URL rather than geometry in the response), plus cost and auth prerequisites. For a three-parameter export tool this covers everything needed to call it correctly and interpret the result.

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

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

Schema description coverage is 100% and the schema already documents the id formats, the four detail levels with point counts, and each format. The description only restates the format list and references 'a detail level' without adding meaning, 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 and resource ('Builds a boundary's polygon as a file'), enumerates the five supported formats and the detail-level dimension, and makes the output explicit (permanent public CDN URL, REST route redirects). It stops short of naming the sibling it contrasts with (get_boundary for inline geometry), so the differentiation from siblings is implied rather than stated.

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?

'Use it for large polygons, GIS tools and bulk downloads' gives a clear when-to-use context, and 'each file is built once and then shared' explains why repeat exports are cheap. There is no explicit when-not or named alternative (e.g., use get_boundary instead when you just need the geometry inline), so the agent must infer the boundary case.

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 context the annotations cannot: the call is free, auth can come from an api_key, oauth or session, and plan/usage/limits belong to the organization and are shared by its members and keys. It does not discuss staleness or caching of usage counters, which is a minor 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?

The what-is-returned clause is front-loaded, followed by scoping and then actionable when-to-use guidance. The opening sentence is a long comma-spliced enumeration and could have been split for scannability, but every clause carries information about return values that has no output schema to document it.

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 full burden of describing the response, and it does so across account, organization, role, auth method, plan, limit usage and next-plan checkout_url. Auth requirements and the free/shared-org semantics are also covered. Only the cross-references to closely related sibling tools are absent.

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 there is nothing for the description to disambiguate and the baseline applies. The description usefully does the inverse job of explaining what the (empty) call returns, including the distinction that plan, usage and limits are organization-scoped rather than caller-scoped.

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 signed-in account and the organization the call acts in" is a specific verb-plus-resource statement, and the enumeration that follows (email/profile, org id/slug/name/type, role, auth method, plan, limits, checkout_url) makes the returned shape concrete. It does not, however, distinguish itself from siblings like get_usage, get_subscription, get_pricing or list_orgs, whose subject matter overlaps with what this tool returns.

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 trigger conditions are given: call before a large batch to check whether it fits, and after a human pays to see the new plan. It also names a prerequisite ("Needs an API key or a connected account"). What is missing is routing guidance versus the overlapping siblings, e.g. when to prefer get_usage or get_subscription over this composite call.

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 well beyond the annotations by disclosing cost (free), link lifetime (does not expire), the sign-in-to-Geocode-AI handoff before the portal opens, the no_subscription failure mode, and the auth requirement (API key or connected account). It leaves one gap: it never clarifies that generating the link itself does not mutate billing state, which is the natural question raised by readOnlyHint=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 core deliverable and packed with high-value facts in a compact space. The middle sentences become somewhat run-on, stacking link lifetime, sign-in flow, and failure mode without separation, but almost no wording 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?

With no parameters and no output schema, the description must carry the entire burden, and it does: it covers what is returned (a URL), its lifetime, the sign-in step, the cost, the auth prerequisites, and the specific error case. An agent has everything needed to call this and set expectations for the user.

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 there is no parameter semantics to explain and the baseline of 4 applies. Nothing in the description is needed to disambiguate inputs, and nothing misleading is present.

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 (produce a Stripe Customer Portal link for the account owner) and enumerates exactly what the recipient can do with it: download invoices, change card/billing details, switch plans, cancel. This clearly separates it from siblings like create_checkout_link, get_subscription, and get_pricing.

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 by 'for the account's owner' plus the no_subscription failure case, which tells the agent this only applies to accounts with a past paid plan. However, it never explicitly says when to prefer this over create_checkout_link or get_subscription, so the alternative selection is left to inference.

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 cover the safety profile (readOnly, idempotent, non-destructive, open world); the description adds genuinely new behavior: a first-request OSM fetch followed by cache serving, a 1-unit cost, and a keyless tier for low detail. It also discloses the failure mode where oversized polygons return geometry=null with a download_url, which an agent cannot infer from structured fields.

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 dense sentences, front-loaded with the return shape before cost, tiering and truncation caveats. Every clause carries information an agent would otherwise have to discover by trial.

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 describing the returned Feature, listing the property keys, and explaining the null-geometry plus download_url fallback. For a single-resource read with trivial side effects, nothing needed for a correct call 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%, so the baseline is 3, but the description adds meaning beyond the schema by tying detail to key tier ('detail=low is also public without a key') and clarifying that include=parents pulls the full hierarchy while children gives direct subdivisions only. Coordinate precision and id format are left entirely to 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 ('Returns one boundary as a GeoJSON Feature') and immediately enumerates the payload: polygon plus named properties. The singular 'one boundary' also distinguishes it from search_boundaries and list_children without opening their 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?

Gives concrete operational context: costs 1 unit, detail=low works without a key for map previews, and include=parents/children selectable extras. It does not name an alternative tool or an explicit when-not-to-use condition (e.g. vs search_boundaries when the id is unknown), 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 cover read-only, idempotent, non-destructive, and closed-world, so the bar is lower, yet the description still adds real context: the call is free (no quota cost) and sign-in codes are always sent regardless of these settings, a caveat an agent would otherwise misreport. It does not disclose whether the switches reflect account-level or org-level scope, or what the defaults are.

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 payload description is front-loaded and every sentence carries information; nothing is padding. The clipped fragments ('Free.' 'Sign-in codes are always sent.') read telegraphically but stay scannable and short.

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 no parameters, the description has to carry the return-shape burden and largely does by listing the global subscription plus one switch per email kind. It falls short only on exact field names, value types, and defaults, which an agent would need to interpret the response programmatically.

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 the baseline is 4. The description's enumeration of switch kinds describes the return payload rather than inputs, which is a bonus given there is no output schema.

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

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

The description names the resource precisely (automated email preferences for the account) and even enumerates the individual switches returned (getting-started notes, first boundary, usage milestones, quota warnings, check-ins, monthly digest), so an agent knows exactly what data comes back. It never names the sibling update_email_preferences, so differentiation from the write counterpart is left to the name alone.

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 can infer this is the read step before update_email_preferences, but the description never says when to call it or when not to. The closing line 'Needs an API key or a connected account' is a genuine access precondition, which is useful, but it is auth guidance rather than call-selection guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety bar is met without the description. The description goes beyond them by disclosing access-control behavior (no key needed for public items; private items restricted to reporter and team) and by describing what the response contains, including marked official team responses and a status timeline.

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 first front-loads what is returned, the second carries the access rule. No filler, no repetition of the title or annotations.

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 correctly takes on the job of describing the payload (status, upvotes, comments, timeline) and the auth model. It is nearly complete for a single-parameter read tool; only error/not-found behavior for a bad or inaccessible id is 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 100% and there is only one parameter, whose schema description already explains that the id originates from list_feedback, request_feature or report_issue and gives an example. The description adds nothing further about the id, so the baseline of 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 opens with a specific resource and enumerates what the single item carries (status, upvotes, comments with official team responses marked, status-change timeline). 'One feedback item' implicitly contrasts with list_feedback, though it never names that sibling explicitly, so an agent must infer the singular-vs-list split.

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 context is implied by the retrieval framing and the schema note that the id comes from list_feedback/request_feature/report_issue, but the description itself never states when to fetch a single item instead of calling list_feedback or get_my_review. It does add a useful access condition (public items free, private issues visible to reporter and team) that shapes whether the call will succeed.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds value beyond that: it flags that the operation is free, that authentication is required, that the download url is permanent, and that sharing information is returned only 'when you can manage it' — a conditional result shape an agent could not infer from structured fields.

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 listing the returned attributes, followed by a short cost/auth note. Dense but waste-free; only the fragment 'Free.' is slightly clipped in phrasing.

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 full annotation coverage and no output schema, the description compensates by enumerating the returned fields and their conditional availability. Nothing critical for correct invocation 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?

There is a single parameter with 100% schema description coverage, and the schema already explains that the id comes from list_files or save_file. The description adds no format, validation, or fallback guidance for the id, so the baseline of 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 exact resource (a single library file) and enumerates what it returns — boundary, format, detail, visibility, access, permanent download url, and sharing info. That is specific enough to separate it from list_files and get_boundary, though it relies on the title's verb 'Get' rather than stating retrieval explicitly in the body.

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: fetch the details of one known file. The prerequisite ('Needs an API key or a connected account') is stated, but there is no explicit when-to-use versus list_files or update_file, and no exclusion 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 declare readOnly, idempotent, openWorld and non-destructive, so the safety bar is covered. The description adds real value beyond them by describing the exact status vocabulary and the presence of a team response, which an agent cannot get from the annotations or an empty schema.

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 first sentence is front-loaded and information-dense, but the trailing 'Free; needs a key. Needs an API key or a connected account.' says the same auth requirement twice in two different phrasings. Halving that tail would lose nothing.

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 zero-parameter, read-only lookup with no output schema, the description supplies the salient return semantics (status values, hidden reason, team response) and the auth prerequisite. The only gap is that the tool does not say what happens when no review exists, which 'if you posted one' only gestures at.

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, which is the baseline-4 case, and the description correctly signals this is a self-scoped lookup requiring no input identifiers. Nothing further is needed or expected 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?

The description names a specific verb ('get') and resource ('your review of the product') and enumerates the returned content: status (published, pending, hidden with reason) and the team's response. That distinguishes it from list_reviews and list_my_feedback, though the phrase 'the product' is never defined and there is no explicit sibling callout.

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 conditional 'if you posted one' implies when this tool is applicable, but there is no explicit routing to list_reviews or list_my_feedback for the cases where the agent wants all reviews or a broader feedback list. Usage is inferable 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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new context: the call is free, requires no API key, and returns per-call unit costs plus which capabilities work unauthenticated. It could go slightly further on result size or caching, but the auth and cost model is well disclosed.

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?

Return contents are front-loaded, followed by cost/no-key behavior and then usage triggers. The first sentence is a dense run-on list of fields, but every clause carries information an agent needs; 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?

There is no output schema, so the description must describe the return payload, and it does so field by field (prices, units, limits, features, checkout_url). Combined with the auth disclosure and invocation triggers, an agent has everything needed to call and interpret it.

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 there is nothing to disambiguate and the baseline of 4 applies. The description correctly implies a single unfiltered catalog response rather than a parameterized query.

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 a specific resource (plans and prices) and enumerates exactly what comes back: monthly price, included units, limits, features, checkout_url. An agent can distinguish it from get_subscription or get_usage immediately, since those are about the account rather than the catalog.

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 triggers are given: before a large batch, when a human asks about cost, or before create_checkout_link. It also supplies a negative rule ('never quote prices from memory') and names the dependent sibling (create_checkout_link), leaving nothing to inference.

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, closed-world, so the safety profile is covered. The description still adds real value beyond that: the call is free, it requires an API key or connected account, and it discloses eventual consistency ('plan changes from free to the plan bought, usually within seconds').

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?

Information-dense with no filler, but the opening sentence is a long comma-laden list of return fields that delays the when-to-use guidance into the third sentence. Front-loading the call triggers would improve it slightly.

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 carries the return-value burden, and it does so thoroughly — enumerated fields, next-plan upsell data, and checkout_url. Auth requirements and the 'free' cost model round out what an agent needs to call it correctly.

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

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

The tool takes zero parameters, so there is no parameter meaning to add; a 4 baseline applies. The description correctly does not waste space on parameter syntax.

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 pair and enumerates the returned fields (plan, status, renewal date, cancel flag, price, this month's limit usage, next plan, checkout_url). It also explicitly differentiates from the nearest sibling: 'The same as get_account without the profile.'

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

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

Gives explicit when-to-use triggers: 'Call it before suggesting an upgrade, and after handing a human a checkout link to see when the payment went through.' It also names the alternative (get_account) and the condition that would select it, plus the constraint 'Free.'

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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely useful pre-call context: the auth requirement (API key or connected account) and the fact that results span every member and key rather than the caller's own activity. It doesn't describe pagination or volume limits, keeping it out of the 5 band.

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 what is returned, then when to use it, then the prerequisite. Every sentence carries information; the only mild duplication is restating the default that the schema already declares.

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 describing returns, and it does so adequately: daily granularity, grouped by op, with cache hit counts, org-wide. The unit of "usage" (requests vs. cost) is only implied by the bill reference, which is the one remaining ambiguity for a single-parameter read 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?

There is a single parameter and schema coverage is 100%, with the schema already documenting the default of 30 and the 1-90 bounds. The description repeats the default and calls the value "N" but adds no new syntax or interpretation beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource (retrieves the organization's daily usage for the last N days) plus the aggregation dimensions: by op, cache hit counts, across every member and key. That granularity separates it in spirit from list_audit_log or get_billing_link, though no sibling is named 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?

"Use it to explain a bill or spot a runaway client" gives two concrete use cases, which is clear context for selection. It stops short of naming an alternative or a when-not condition, so it falls just below the top band.

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

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

The description adds substantial value beyond the annotations by disclosing authorization scope, returned fields, the exclusion of secrets, and behavior for departed users' keys. It also states authentication requirements, which is useful behavioral context for a read-only listing operation.

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, packing the resource, return fields, visibility rules, and authentication requirement into a few dense clauses without unnecessary wording. Every sentence contributes useful 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 read-only listing tool with no output schema, the description is largely complete: it explains what is returned, who can see what, and the authentication requirement. The main gap is the unexplained include_revoked parameter, and pagination or ordering behavior is not addressed.

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

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

The only parameter, include_revoked, is not mentioned in the description, and the schema provides 0% description coverage. While the parameter name is somewhat self-explanatory, the description fails to compensate for the low schema documentation by explaining whether revoked keys are included by default or what the flag changes.

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 identifies the resource as the organization's API keys and specifies the returned fields (prefix, name, creator, last use) while explicitly noting the secret is never returned. This distinguishes it from sibling tools such as create_api_key and revoke_api_key.

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 clear contextual guidance by explaining visibility rules: members see only keys they created, while admins and owners see all keys, including those from departed users. It also states that authentication via API key or connected account is required, though it does not explicitly name alternatives or when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds ordering ('newest first'), the permission gate, and auth requirements — useful context beyond the annotations. It says nothing about pagination behavior or result volume, which is a notable gap for a logged, potentially large dataset.

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 its contents come first, then the access constraints. Every clause carries information — the actor types, the change categories, ordering, permission level, cost, and auth. Minor density without wasted words.

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

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

For a read-only, three-parameter list tool with no output schema, the description covers scope, ordering, permissions, cost, and auth — enough to call it correctly. The remaining gap is pagination semantics for offset/limit, which matters somewhat for a log-shaped resource but is partially handled by the schema.

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

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

Schema coverage is 67%: limit and action are documented in the schema, while offset has no description anywhere. The description adds no parameter-level meaning — no guidance on action naming beyond what the schema's example already gives, and no clarification of how offset interacts with the 'newest first' ordering. Baseline 3 is appropriate given partial schema coverage.

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

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

The description names the specific resource (the organization's audit log) and enumerates the event categories it covers — membership, roles, teams, invites, API keys, billing, file sharing — plus who performed them. That is concrete enough to distinguish it from siblings like list_members or list_api_keys. It stops short of explicitly naming a non-overlapping sibling, so it lands at 4 rather than 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?

It gives real access guidance: admins and owners only, no cost, requires an API key or connected account. What it omits is when to reach for this versus adjacent tools (e.g. list_members for current state versus this for historical change), so usage is implied rather than directed.

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, openWorld and non-destructive, so the safety profile is covered. The description adds that the service is "Free and public" (a cost/auth signal) and restates the default-level resolution, but says nothing about result shape, ordering, pagination, or what happens when a boundary has no children. Useful but thin beyond the structured fields.

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 concept and examples come first, followed by the default rule, then cost, then use cases - a sensible front-loaded order across four short sentences. The standalone "Free and public." fragment is terse but earns its place as a cost signal; otherwise near-zero waste.

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 only two parameters and rich annotations, the description covers concept, defaulting, and purpose. However, there is no output schema, so the description should say what a returned subdivision looks like (identifier format, name, admin_level) and whether an empty result is possible for a leaf boundary - an agent cannot infer that from anything supplied.

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 the id formats and the admin_level range/default are already fully documented in the schema. The description's only parameter-relevant sentence repeats the default resolution rule already present in the admin_level field description, adding no new meaning. 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 exact resource (the direct subdivisions of a boundary) and illustrates the hierarchy with concrete examples (country->states, state->counties, city->districts), so an agent knows precisely what comes back. It does not explicitly contrast itself with siblings like get_boundary, search_boundaries, or contains_points, leaving the distinction to inference from names.

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?

"Use it to build drill-down pickers or to cover a region with its parts" gives a concrete use context, and the admin_level default rule tells the agent it can call it without any level argument. There is no when-not guidance or explicit alternative (e.g. use get_boundary for the parent itself), which keeps it below 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered; the description adds real value by stating default ordering ('most upvoted first'), that the tool is free and needs no key, and that a key unlocks private issues and vote state. It does not cover pagination behavior or response shape, which keeps it from a 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?

Two sentences, front-loaded with what the board contains and the ordering, followed by the routing guidance. Dense but every clause carries information; minor cost is that the first sentence packs several facts together.

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 an 8-parameter read tool with no output schema but full annotation coverage, the description supplies purpose, ordering, auth requirements and the decision context needed to invoke it. Pagination and the return item shape are left to the schema, which is acceptable.

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 every parameter including sort defaults, enum meanings, and page-size limits is already documented in the schema. The description's only extra hint is the default 'most upvoted first' ordering, which duplicates the sort default, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('The feedback board: feature requests and published issues with their status and upvotes') plus the ordering, and distinguishes itself from the related collection by noting that with a key it also returns private issues and vote state. An agent can tell what this returns without opening the schema.

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

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

Gives explicit when-to-use guidance: call before request_feature or report_issue to find an existing item to upvote instead of filing a duplicate, or when the human asks what is planned or shipped. It names the alternatives and the condition that selects this tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, and the description still adds real context beyond them: visibility rules (org-visible plus team/personal shares), ordering (newest first), the per-item access level returned, cost ('Free'), and the auth requirement (API key or connected account). That is substantive behavioral detail an agent cannot get from the structured fields.

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 key scoping constraint is front-loaded and the trailing short clauses (access level, cost, auth) are terse and information-dense. The opening sentence is long and stacks several ideas, but no sentence 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?

With no output schema, the description does the work of describing what comes back: file identity, access level, and newest-first ordering. Pagination semantics (whether offset pages through a stable ordering, total counts) are the notable omission for a list endpoint with two paging parameters.

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 50% — limit is documented but offset carries no description — and the description mentions neither parameter, not even that results are paged. 'Newest first' hints at ordering but there is no parameter to control it, so the description does not compensate for the schema gap.

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

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

The description names a specific resource (boundary files in the organization's library) and its scope (org-visible plus restricted files shared with you or your team), which separates it from get_file and search_boundaries. It never names a sibling explicitly, so differentiation is by implication rather than direct routing.

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 visibility scoping ('what you can see') implies the browse-everything use case, but there is no explicit when-to-use or when-not-to-use guidance, and no pointer to search_boundaries or get_file for filtered or single-file lookups. The agent must infer the split from sibling names.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint, so the safety profile is covered; the description adds genuinely new context: admin/owner-only authorization, no cost, and the fact that mutating invite operations are unavailable through this tool. The status vocabulary (pending, accepted, expired, revoked) also tells the agent what values to expect.

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 compact and front-loads the resource and returned fields before the access and cost notes. The dashboard-mutation sentence earns its place as a scope boundary, though the colon-separated field list reads more like schema echo than prose.

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 usefully enumerates the returned fields and their possible statuses, plus auth requirements. The one gap is that it never states the default behavior, that accepted/expired/revoked invites are excluded unless include_closed is set, which an agent must infer from the schema.

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

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

Schema description coverage is 100% and the single parameter include_closed is documented in the schema, so the description need not restate it. The description does not reference include_closed at all, so it adds no meaning beyond the schema; 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 resource (invitations to the organization) and enumerates the fields returned (email, role, teams, status, expiry), so an agent knows exactly what this retrieves. It never uses an explicit verb like 'list', relying on the title, but the content is unambiguous and differentiated from list_members by the invite framing.

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 states the access restriction ('Admins and owners only'), the cost ('Free'), and the auth options ('API key or a connected account'). It also draws a clear boundary by saying sending/resending/revoking happens on the dashboard, which tells the agent this tool is read-only. It does not point at a sibling tool for related tasks such as checking current membership.

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 read-only, idempotent, non-destructive, closed-world operation, so the safety bar is low. The description still adds two things not in the annotations: the call is free, and it requires an API key or a connected account.

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 sentence fragments with the resource and payload front-loaded, then usage, then the exclusion and auth note. Nothing is redundant, though the telegraphic style is terse enough that a little connective wording would read more cleanly.

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 listing the fields a member record contains plus the auth prerequisite and the zero-cost trait. Pagination or ordering behavior is not mentioned, which is a minor gap for a list endpoint that returns every member.

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 no parameters, so there is no parameter meaning to convey and the baseline applies. The description usefully redirects that space toward the shape of the returned record instead.

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 resource precisely and enumerates the returned fields (email, name, role, join date, teams), which makes clear this is a read of organization membership. It stops short of explicitly distinguishing itself from the sibling list_teams, so an agent must infer that boundary itself.

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?

'Use it to find who to share a file with' supplies a concrete use case, and 'Inviting, removing and changing roles is done by a person on the dashboard' rules out the mutation cases an agent might otherwise attempt. There is no explicit pointer to a sibling tool for the adjacent operations, so it is clear rather than exhaustive.

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 read-only, idempotent, non-destructive, and open-world behavior. The description adds useful context beyond those fields: it is free, requires an API key or connected account, includes private issues, and returns current status for each item.

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

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

The description is front-loaded and generally readable, but the authentication requirement is stated twice: 'Free; needs a key' and then 'Needs an API key or a connected account.' That duplication and fragmented phrasing reduce efficiency.

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 personal list with one optional limit parameter and no output schema, the description covers the key content, status inclusion, cost, authentication, and primary use case. It still omits minor operational details such as pagination or ordering, but is otherwise sufficient.

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

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

Schema description coverage is 100%, and the single limit parameter is already fully documented in the schema. The description adds no additional meaning about limit behavior, so the baseline score of 3 is appropriate.

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

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

The description clearly states the personal scope: items you filed (including private issues), items you follow through votes/comments, and your review, each with status. It distinguishes a personal list from the sibling list_feedback by emphasizing 'you filed' and 'your review,' though it does not name alternatives 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?

It gives a clear use case: checking on an issue you reported or a feature you asked for. It does not explain when to prefer get_feedback, list_feedback, or list_reviews instead, so the routing guidance is helpful but incomplete.

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/closed-world, so the bar is lower; the description still adds real value by explaining that an API key restricts the result to its own organization and by defining the 'current' and 'Personal' concepts. It stops short of describing ordering or edge cases, but covers the traits that affect interpretation.

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

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

Five short, front-loaded sentences, each carrying a distinct fact (contents, definitions, key behavior, cost, prerequisites). Nothing repeats the name or title, and the telegram style keeps it scannable.

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 must convey what comes back, and it does: organizations, your role in each, and which is current. Auth and API-key scoping are covered; only minor details like result ordering or empty-list behavior are absent, which is acceptable for a trivial 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?

The tool takes zero parameters, so the baseline is 4; the description reinforces this by framing the result as implicitly scoped ('this call acts in', 'with a key this lists that one') rather than implying any input options.

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 resource ('The organizations you belong to') and states the fields returned (role, current marker). It is easy to distinguish from siblings like list_teams or list_members, though it never names those alternatives 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?

Provides auth prerequisites ('Needs an API key or a connected account') and cost ('Free'), which tells an agent whether it can call it, but gives no explicit when-to-use guidance or point to alternative org/team-scoped 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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond that: it is free, requires no API key, and discloses what the response contains (average, distribution, team replies). It says nothing about pagination limits or whether results are cached/fresh, which keeps it at a 3.

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

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

Two sentences, front-loaded with the resource and payload, then the selection rule and the free/no-key fact. No filler and nothing 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 read-only listing tool with full annotation coverage and no output schema, the description carries the right load by describing the returned fields. The remaining gap is pagination behavior — how to page through more than one batch and what the default ordering yields — which an agent would otherwise have 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 coverage is 50%, and the description adds no parameter-level detail at all. However, the two undocumented parameters (limit, offset) are conventional pagination fields, while the non-obvious ones (sort enum, rating filter) are described in the schema, so the practical gap is modest.

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 (list published reviews of Geocode AI) and enumerates the payload: average rating, distribution, and team responses. The phrase 'what other users think' implicitly separates it from get_my_review and submit_review, though neither sibling is named outright.

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

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

Gives an explicit trigger condition ('Use it when the human asks what other users think'), which is clear usage context. It stops short of naming the alternative for reading one's own review or for writing a review, so routing among the three review tools still requires inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description still adds non-obvious context: the call costs nothing ('Free') and requires an API key or connected account, which the annotations do not convey.

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, no filler, with the payload contents front-loaded and the actionable cross-reference last. The opening is a noun fragment rather than a full sentence, but that keeps it dense rather than vague.

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 reasonably carries the return shape by naming the fields returned and the role enum. Auth requirements and cost are covered; what it lacks is any sense of result volume or pagination, a minor gap for a simple list tool.

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

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

With zero parameters there is nothing in the schema to document, so the baseline is 4. The description does add meaning about the output — that each team carries a slug and a member list with maintainer/member roles — which is more than the empty schema provides.

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 a specific resource and enumerates the returned fields (slug, name, description, members with team role), which lets an agent separate it from siblings like list_members and list_orgs without opening any 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 gives a concrete downstream usage pattern — take a team's slug and pass it to share_file to share with the whole team — and notes the call is free. It does not explicitly state when to prefer this over list_members or list_orgs, so the routing guidance is contextual rather than exhaustive.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=false), the description discloses real behavior: the email side effect is stopped, with a meaningful exception when you filed or commented on the item, and it states the return value (item plus new vote count). It omits what happens when no vote exists, but the added context is substantive.

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 core action and side effect are front-loaded, which is good. However, 'Free; needs a key' and 'Needs an API key or a connected account' restate the same requirement in one short paragraph, wasting one of only three sentences.

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

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

For a one-parameter mutation with no output schema, the description covers purpose, auth, side effects, and the return shape. The main remaining gap is error behavior when no upvote exists, which the non-idempotent hint makes relevant.

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 'id' parameter is fully documented in the schema, including where the id comes from. The description adds no additional meaning about the id, so the baseline of 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 uses a specific verb and resource ('Takes back your upvote on a feature request or issue'), which implicitly and cleanly distinguishes it from the sibling upvote_feedback. An agent can tell exactly what object is being mutated without opening the schema.

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

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

Usage is implied by 'takes back your upvote,' but the description never names upvote_feedback as the inverse alternative or states a precondition such as already having voted. It does note the key requirement, which is a useful gate, but there are no explicit when-not 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 only declare the generic profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false); the description adds substantially beyond that: visibility limits (issues are private to you and the team), the two-phase dry-run-then-file behavior, daily quota (10 new items per account per day), cost (free), auth requirement (API key), and a side effect the agent cannot otherwise see — a human is emailed on filing and on every status change.

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

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

Front-loaded with purpose and trigger before mechanics, and no sentence is filler. The middle portion is densely packed into semicolon-and-em-dash chains ('Free; needs a key; 10 new items per account a day'), which reads telegraphically and slightly hurts scannability, but nothing is 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 non-idempotent write tool with a nested context object and no output schema, the description covers everything an agent needs: auth requirement, rate limit, privacy of the payload, that the first response is similar issues rather than a filed record, the force override, and the human-notification side effect. No return-value explanation is owed here because it explains the one non-obvious response behavior itself.

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, but the description earns above baseline by tying parameters to the workflow: where request_id comes from (X-Request-Id header or the error body's request_id), that op should match the failing call's op, and that force: true is specifically the escape hatch when similar issues were returned. It adds little about title/details beyond what the schema already states.

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 a specific verb and resource (report a problem / issue) and scopes it with concrete categories: a failing or wrong API call, a wrong or missing boundary, a docs error. That enumeration distinguishes it from an agent's likely confusion partners such as request_feature (new capability) or comment_on_feedback (commentary), and it points at upvote_feedback as the alternative action for a duplicate.

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 an explicit trigger condition ('Call it after a call fails in a way that looks like our bug (5xx, a wrong polygon, a boundary that should exist)') rather than a vague 'use when appropriate'. It also resolves the duplicate case: the tool first returns similar issues without filing, and the agent should either upvote_feedback the same one or pass force: true — an explicit alternative path rather than inference.

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 well beyond the annotations by disclosing the dedup-then-abort behavior and the `similar` return, the force override, cost and rate limit (free, 10 new items per account per day), auth requirement, side-effect emails, and public visibility of the post. It also states a privacy constraint (never the author's email) and an explicit data-hygiene rule. Nothing here contradicts destructiveHint=true or openWorldHint=true; the public, hard-to-retract nature of the post is consistent with them.

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

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

Dense but front-loaded: the action and the primary when-to-use condition come first, then dedup behavior, then cost/auth/limits, then privacy constraints. Every sentence carries information an agent would otherwise have to guess, including the rate limit and the public-visibility 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 3-parameter write tool with no output schema, the description covers trigger, alternatives, dedup semantics, override, cost, quota, auth, side effects, and privacy. There is no meaningful gap an agent would need filled before calling it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: `force` is explained as the escape hatch when similar requests exist, and the `similar` response field is described. `title` and `details` are left to their schema descriptions, which is acceptable given full 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?

States a specific verb and resource — 'Files a feature request on the public board and upvotes it for you' — and immediately contrasts it with `upvote_feedback` and (later) private issues. An agent can distinguish it from siblings like report_issue or comment_on_feedback 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?

Gives an explicit trigger ('when the human wishes the API did something it cannot') with concrete examples of what counts (boundary type, export format, op or option). It also names the alternative path: when similar requests match, file nothing and use upvote_feedback, or pass force to override.

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 this as a read-only, open-world, idempotent, non-destructive lookup. The description goes beyond them with cost (1 unit), an auth prerequisite (API key or connected account), and the fact that results are ids to feed into get_boundary. That is meaningful operational context, though it doesn't specify rate limits or result ordering guarantees 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?

Four short sentences, front-loaded with what the tool returns and the hierarchy it returns it in. Each sentence adds distinct information: output content, use case, cost, auth, and chaining to get_boundary, 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?

For a two-parameter lookup with no output schema, the description covers what comes back (ids), cost, auth, and the natural next call, which is enough to invoke it correctly. It could say more about the shape of each returned boundary entry, but the essential calling information is present.

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 both lat and lon carry range and unit descriptions, so the input side is fully documented structurally. The description adds nothing beyond implying a single 'point', which is the expected baseline when the schema does all 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?

The description states a specific operation on a specific resource: every administrative boundary containing a point, ordered country down to smallest district plus postcode areas. That wording distinguishes it from siblings like contains_points and search_boundaries without the agent needing to open their 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?

It gives a concrete use case (tag an address, store, or delivery with country, state, county, city in one call), which tells the agent the scenario this tool is for. It stops short of explicitly naming when to prefer contains_points or search_boundaries instead, so it is strong context rather than a full routing rule.

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, and the description adds real value on top: the immediate 401 effect on requests using the key, the permission scoping model, and the auth prerequisite. That is exactly the operational consequence an agent needs before committing to an irreversible 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, front-loaded with the action and effect, then permissions, then auth. No filler and nothing repeated from 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?

For a one-parameter destructive mutation with no output schema, the description covers effect, permission model, and auth requirement. Nothing an agent needs before calling 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 single id parameter is fully documented with a UUID pattern and provenance ('from list_api_keys'), so the description needn't carry more. It adds only the 'by id' framing, which is the expected 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 and resource ('Revokes an API key by id') and the id format is pinned to the sibling producer, list_api_keys. An agent can distinguish this from create_api_key and list_api_keys 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?

Gives clear context on who may call it (members revoke their own keys, admins/owners revoke any key in the org) and the auth requirement. It stops short of naming exclusions or explicitly routing to alternatives such as list_api_keys to find the id, but the usage conditions are well specified.

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 well beyond the annotations by disclosing cost (1 unit), auth requirement (API key or connected account), the semantics of the two visibility modes, and the dedupe rule (same boundary+format+detail returns the existing entry). Note a mild tension with idempotentHint=false, but that is defensible since name/visibility can differ on a repeat call, so it is not a contradiction.

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

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

Front-loaded with the core action, then side effects, then cost/auth in a compact block with zero filler sentences. It is dense to the point of being one long paragraph, but nothing meaningful could be cut without losing routing or safety context.

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

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

With no output schema, the description still declares the return value (the library entry with its permanent download URL). Combined with auth, cost, dedupe, and visibility semantics, an agent has everything needed to call this correctly.

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

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

Schema coverage is only 40%, and the description compensates by explaining what visibility actually does (org = every member at their role; restricted = you, admins, and share_file recipients) and that name defaults to boundary+format+detail. The detail and format enums are left for the schema to speak for themselves.

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 (exports a boundary and saves it in the org's file library) and explicitly contrasts with export_boundary (export only) and links forward to list_files and share_file. An agent can place it precisely among the siblings without opening the schema.

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

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

Names the alternative (export_boundary) and the reason to choose this one (persistence + discoverability on the dashboard/through list_files), plus which tool to use afterwards for sharing (share_file). It doesn't give an explicit 'do not use this if…' exclusion, which keeps it 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 declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description still adds genuine behavioral context beyond them: 'Free and public', the exact returned fields, and the important limitation that no polygon is included.

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 tightly packed sentences: what it finds, how to narrow it, what comes back and what to do next. No filler, and the core purpose is front-loaded before the filter and return details.

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 compensates by enumerating the returned fields (id, kind, admin_level, country, parents, bbox, centroid, population) and flagging the absent polygon. Combined with the onward pointer to get_boundary, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so all six parameters are already documented, including the enum and the lat,lon pattern. The description restates which filters exist ('country, kind or admin_level', 'bias toward a point with near') but adds no syntax or semantics beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource — 'Finds administrative boundaries ... and postcode areas by name, in any language' — and enumerates the covered kinds. An agent can distinguish this from reverse_boundaries or get_boundary from the description alone.

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 routes the agent onward: results carry no polygon, 'pass the id to get_boundary for that', which is a real when-to-use-next rule. It does not, however, distinguish this from siblings like reverse_boundaries (coords → boundary) or contains_points, so the exclusion coverage is partial.

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 well beyond the annotations by disclosing the authorization requirement, the viewer privilege cap, that repeat calls mutate rather than duplicate, that there is no cost, and that it authenticates via API key or connected account. The annotation set already flags destructiveHint=true, so the remaining gaps (exact shape of the returned shares list) are minor.

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

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

Front-loads the action and target, then layers prerequisites and caveats in short clauses with no filler. Slightly dense and semicolon-heavy, and the one-word 'Free.' is terse, 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?

Covers what an agent needs for a mutation tool: who can call it, what the access ceiling is, auth mode, and that shares are returned. With no output schema, the return value is only named rather than described, which is the one loose end in an otherwise complete definition.

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?

Adds meaning past the 75%-covered schema: it names both identifier forms for team (slug or id) and user (email or user id), and explains that the access value on a repeat call overwrites the prior grant. The access enum itself has no schema description, so the description's read/write/admin framing carries real weight.

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 (share a library file) plus the full target space (team by slug/id, person by email/user id) and access levels. The clause 'sharing again changes the access' also separates it from unshare_file and from creating a duplicate share, so an agent can route correctly without opening the schema.

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

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

Gives clear preconditions — you need admin access on the file as creator, org admin, or admin share — and the caveat that viewers are capped at read regardless of the requested level. It does not name unshare_file as the removal alternative, relying on 'sharing again changes the access' as an implicit hint.

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 substantial behavior beyond the annotations: moderation rules (pending if the review holds links or the account is under a day old), a rate limit (one edit an hour), version retention, a thank-you email side effect, cost (free), and auth requirements. Annotations only say non-read-only, destructive, non-idempotent, open-world; the description supplies the operational detail an agent actually 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?

Front-loads purpose and replacement semantics, then adds constraints and side effects in short clauses. Dense but mostly waste-free; the semicolon-chained delivery of free/auth/rate-limit details is slightly run-on, though each fact 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?

Covers the high-risk aspects for a 9-parameter public mutation: moderation outcome, rate limit, auth, versioning, and side effects. No output schema exists, so an agent may still be unsure what the response contains (e.g., published vs pending status, review identifier), which is the main remaining 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 100%, so field meanings and limits are already documented in the schema. The description loosely maps the content fields ("1–5 stars, what they like and dislike, what they use it for") and adds the constraint that values must come from the human, but it does not explain display_name defaults or marketing_consent 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?

Names a specific verb and resource ("Posts the human's public review of Geocode AI") and immediately discloses the upsert semantics ("or replaces their existing one; each account has one review"). This distinguishes it from siblings like get_my_review and list_reviews, which read rather than write.

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 a clear constraint on when/how to call it: "Only call it with the human's own rating and words, never invented ones." It stops short of naming alternatives (e.g., get_my_review to inspect an existing review before editing) or stating when not to call, but the context is unambiguous.

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 well beyond the annotations with information the annotations cannot convey: a cost model (1 unit per boundary), a hard cap of 50 boundaries, the return shape (GeoJSON Feature with area_km2), and the authentication requirement (API key or connected account). The readOnly/idempotent/non-destructive profile is consistent with a pure geometric computation, so nothing is contradicted.

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 short sentences, each carrying distinct payload: operation definition, use cases, limits and cost, return type and alternative. The core semantic ('union of include minus union of exclude') is front-loaded in the first clause, so an agent skimming the opening already gets the operation right.

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 naming the return type and its key field (area_km2). For a three-parameter computation tool, limits, cost, auth, and routing to the sibling cover everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3; the description lifts it by explaining the set algebra between include and exclude and illustrating it with a worked example, which tells the agent how the two arrays interact rather than just what each holds. The detail parameter's simplification levels are left entirely to the schema, so it stops short of a 5.

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 (merges) and resource (boundaries) and then defines the exact set operation: 'the union of include minus the union of exclude,' with a concrete example of three counties minus one city. This clearly separates it from create_area (word descriptions), contains_points, and reverse_boundaries without requiring the schema to be opened.

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 concrete use cases (sales territories, delivery zones, service areas), names an explicit alternative for the different need ('to describe an area in words instead, use create_area'), and states operational limits (up to 50 boundaries). The agent knows both when to reach for it and where to route elsewhere.

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 destructive/non-idempotent, but the description adds genuinely new behavior: admin access is required, org-visible files remain visible to all members after the grant is removed, and the call is free with API-key or connected-account auth. It does not say what happens when the grant id is unknown or whether access revocation is immediate.

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

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

Front-loaded with the action, then permissions, then edge-case semantics, then cost/auth. Extremely dense telegraphic clauses ('Free.') are efficient but make it read like notes rather than prose; nothing is wasted, though.

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 destructive mutation with no output schema, it covers auth, admin requirement, the key side-effect caveat (org visibility persists), and the remedy path. Only the failure/response behavior is 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 only 50% — grant_id has no schema description, and the description supplies its provenance ('from get_file'), which is real added meaning. The file 'id' parameter is already documented in the schema, so the description need not repeat it.

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 precise verb+resource with granularity: 'Removes one share of a library file by its grant id.' The emphasis on 'one share' (versus deleting the file or all sharing) lets an agent distinguish this from delete_file and share_file without opening 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 triggering context clearly (revoke a single grant obtained from get_file) and names a follow-up alternative path via update_file for org-visible files. It does not explicitly say when to prefer delete_file or a full unshare-all, so it stops short of full alternative 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?

Beyond the annotations, the description discloses auth requirements, that the call is free, the partial-update rule ('Kinds not named keep their setting'), and the return value ('Returns the preferences after the change'). It also equates a full unsubscribe with the unsubscribe link, which tempers the destructiveHint. It does not state whether the change is logged, confirmed, or how to verify afterward.

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 chain that defines the main switch, then the granular switch, then the partial-update rule, then cost, return, and auth. No clause is filler and nothing important is buried.

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, fully described schema with no output schema, the description covers action, scope, partial-update behavior, return value, cost, and auth. The only meaningful omission is any pointer to `get_email_preferences` as the non-mutating alternative.

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, but the description adds meaning the schema does not: it explains that `subscribed` is an all-or-nothing global switch and that unspecified `kinds` entries are left untouched, which is the key merge semantic for a nested object.

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 opens with a specific verb and resource ('Turns automated emails on or off') and immediately defines the semantics of both `subscribed` values and the `kinds` map, so an agent knows exactly what the tool mutates. It does not explicitly name the read counterpart `get_email_preferences`, which keeps it from 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?

Clear conditions are given for each mode: `subscribed: false` for a full unsubscribe, `subscribed: true` to resubscribe, `kinds` for individual switches, plus the key rule that unnamed kinds keep their setting. Prerequisites ('Needs an API key or a connected account') and cost ('Free') are stated. It never explicitly says to use this rather than `get_email_preferences` when only reading.

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 non-read-only, destructive, non-idempotent mutation; the description adds real value on top with per-operation permission requirements, cost ('Free'), and authentication needs, which annotations cannot express. It stops short of clarifying what is actually lost when visibility flips to restricted (implied loss of member access) or what the call returns, leaving the destructive hint only partially explained.

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

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

Front-loaded with the action, then the enum semantics, then cost and auth in short fragments — nothing is padding. The first sentence is densely packed with nested parentheticals, which costs some readability but not correctness.

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 mutation with annotations but no output schema, the definition covers the essentials: access requirements, enum meaning, auth, and cost. Minor gaps remain on precedence when both name and visibility are supplied and on the response shape, but nothing blocking an agent from calling it correctly.

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

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

Schema coverage is only 33% (only 'id' is documented in the schema), so the description must carry the load, and it does: it explains exactly what 'org' and 'restricted' mean in terms of who retains access, which is the single most consequential parameter. The 'name' parameter is covered indirectly by 'Renames', and the rename/visibility mapping to the two optional inputs is clear.

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 a specific resource (a library file) and two concrete operations: renaming and setting visibility. It is immediately distinguishable from read-only siblings like get_file or list_files, but it never explicitly contrasts itself with nearby write siblings such as save_file, share_file, or delete_file.

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 states the prerequisite access level for each mode ('write access' to rename, 'admin access on the file' for visibility) and the authentication requirement, which is useful context for whether the call will succeed. However, it gives no explicit when-to-use-this-instead-of guidance and no exclusions, so an agent must infer the boundary against save_file and share_file.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, and the description corroborates the destructive path by explaining that an empty string clears a field, plus it discloses cost ("Free."), auth requirements, and the return value. It does not explain why the operation is flagged destructive or whether there is any confirmation/undo, so it adds context without fully covering the annotation's warning.

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 mutation semantics and field list are front-loaded, then invocation guidance, cost, and auth follow in short sentences with little waste. The one-word "Free." fragment is slightly abrupt but still informative rather than 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 flat four-parameter update with no nesting and no output schema, the description covers purpose, partial-update behavior, clearing semantics, auth, cost, and the return value ("Returns the updated profile"). Nothing needed to invoke 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%, so the baseline is 3 and all four fields are already documented in the schema. The description adds the clearing rule ("an empty string clears a text field") and the send-only-changed-fields convention, which is real value beyond the schema, but nothing about the enum locale beyond restating what schema covers — netting a solid baseline rather than a lift.

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?

"Sets the account's name, company, use case ... and language" names a specific verb and enumerates the exact resource fields, so the agent knows precisely what is mutated. The only gap is sibling differentiation: it never contrasts itself with the adjacent update_email_preferences or get_account tools, which an agent might reasonably confuse given the overlapping 'language for emails' phrasing.

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?

"Send only the fields to change" gives explicit partial-update invocation guidance, and "Needs an API key or a connected account" states the prerequisite. It stops short of when-not-to-use guidance or naming alternatives, such as routing locale changes to update_email_preferences instead.

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

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

The description adds substantial context beyond the annotations: the vote's business effect, the email notification on status change, the duplicate-redirect rule, and the return payload. However, it explicitly claims "Idempotent: one vote per account" while the annotations declare idempotentHint=false, giving the agent a misleading picture of what a repeated 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?

The key behavior (duplicate redirect, one vote per account, return value) is front-loaded, but the auth prerequisite is stated twice — "Free; needs a key" and then "Needs an API key or a connected account" — which is wasted text in an otherwise compact description.

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 mutation with no output schema, the description covers side effects (vote counted, email on status change), auth requirements, and the return value. The only real gap is the conflicting idempotency claim that leaves repeated-call behavior ambiguous.

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

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

Schema description coverage is 100% and the schema already explains that id comes from list_feedback, request_feature or report_issue. The description adds nothing about the id parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ("Adds your upvote to a feature request or issue") and explains the effect ("votes decide what gets built and fixed first"). It does not explicitly name the natural sibling remove_feedback_vote, so an agent must infer the inverse operation from the sibling list.

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 ("a 'me too'", duplicate votes are redirected to the original) and states cost/auth prerequisites. It stops short of stating when NOT to use it, e.g. to un-vote, which would require pointing at remove_feedback_vote.

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