Vicinity Agent API

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

Annotations already communicate read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds a useful non-obvious domain rule: each venue has its own activity band and a city's activity level cannot be used as a proxy. This helps avoid a plausible incorrect inference, though it does not cover response or pagination details.

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

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

The description is two sentences with no filler. The first sentence states the result set and filter dimensions; the second adds a valuable caveat that prevents a common misinterpretation. It is front-loaded and every sentence earns its place.

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

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

For a read-only search tool with 7 fully documented optional parameters and no output schema, the description plus schema is nearly sufficient: it defines the qualifying property and the main filtering dimensions. The main gaps are the lack of explicit sibling routing and the unexplained product jargon, but these do not seriously impair invocation.

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

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

The schema already documents all 7 parameters, so the baseline is 3. The description reinforces the main filter dimensions and adds semantic insight about the activity concept: venue activity is independent of city activity. This goes beyond the bare enum labels, though no new formatting or constraint details are introduced.

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 concrete resource (venues with a standing Vicinity room) and a clear retrieval behavior (find/filter by city, distance, activity, or free text). It is distinguishable from siblings like get_place or list_events, though it does not explicitly differentiate itself by name.

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

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

The description implies when to use the tool: when looking for venues matching certain filters. It does not explicitly state when to prefer this over siblings such as get_place, nor does it give exclusion conditions, so the guidance remains implicit rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that the data is a 'live status' (real-time) and includes counts, which is useful context beyond annotations, but doesn't disclose potential performance or data freshness implications.

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

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

The description is a single sentence that efficiently lists the key deliverables (live status, busiest venues, upcoming event count). It is front-loaded and has no filler words, achieving maximum information density.

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

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

Given the tool's simplicity (1 optional parameter, no output schema, no nested objects), the description covers the main outputs. It doesn't specify the format of venues or event count, but that is likely unnecessary for basic selection. It is complete enough for an agent to know when to call 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?

Schema coverage is 100% and the only parameter 'city' is described as a slug with a default. The description adds no further meaning to the parameter, so it relies on the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns a city's live status, busiest venues, and event count, using specific nouns. It distinguishes itself from get_city_status (which likely returns only status) but doesn't explicitly name alternatives. The title 'One city in detail' reinforces the scope.

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

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

The description implies use when a user wants a city's overview, but does not explicitly state when to use alternatives like get_city_status or what's_happening. It provides no exclusions or conditions, so agents must infer applicability based on the detail level.

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 the live temporal scope ('current activity pulse', 'next 24 hours'), which is useful, but it does not describe behavior for unknown cities or how 'withheld count' is computed.

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 one compact sentence that front-loads the purpose and lists the returned metrics without filler. The only cost is that 'band' and 'withheld count' are packed in without explanation, but the structure itself is efficient.

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

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

The tool is simple—one optional parameter, no nested objects, and thorough annotations—so the description does not need to do heavy lifting. Still, with no output schema, the agent must infer the response shape and the meaning of 'band' and 'withheld count,' which are not defined anywhere.

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

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

The input schema fully documents the only parameter: an optional city slug that defaults to the bound city. The description adds no new meaning about the parameter beyond reiterating the single-city scope, so the schema carries the burden, which is acceptable at 100% 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 tool name and title establish the verb and resource, and the description specifies the exact metrics returned for a single city: band, withheld count, venue count, and upcoming public events. It is clearly scoped to one city, which distinguishes it from list-level siblings, though terms like 'band' and 'withheld count' are unexplained jargon.

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 'one city' scope and optional city parameter imply this is for a per-city status lookup rather than listing or searching. However, the description does not say when to choose this over siblings like get_city or whats_happening, or when not to use it, leaving usage 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 readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds valuable behavioral context by specifying the content returned: live bands, limits, privacy guarantees, and taxonomies. It also hints at the static nature by saying 'Call this once,' implying idempotency. While it doesn't describe return format or size, the annotation coverage lowers the burden, and the description meaningfully extends beyond annotations.

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

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

The description is two concise sentences. The first states exactly what the tool returns, front-loading the core content. The second gives a usage directive. No fluff or redundancy; every clause earns its place.

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

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

For a parameterless, read-only tool with no output schema, the description fully equips an agent: it states what data is returned (coverage, limits, privacy, taxonomies) and when to use it (to explain Vicinity and where it works). There is no missing information that would prevent correct invocation.

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

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

There are zero parameters, so the schema coverage is trivially 100%. The description does not need to elaborate on parameters. Per the rubric, 0 params gets a baseline of 4, and the description adds nothing contradictory or missing.

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 tool as returning 'the full coverage list with live bands, plus the published limits, privacy guarantees, section and event-category taxonomies.' It names a specific resource (coverage data) and the content. It also distinguishes itself from siblings like get_city or list_events by focusing on coverage and limits, so an agent can differentiate it without opening the schema.

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

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

It provides a clear usage context: 'Call this once if you need to explain what Vicinity is and where it works.' This tells the agent when to invoke it. However, it does not explicitly mention when not to use it or name alternative tools, such as get_city for city-specific details. The guidance is clear but lacks exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds useful context: the call is free and reports the current cost of one intent. It does not discuss return structure or failure modes, but that burden is partly reduced by the annotations.

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

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

The description is two sentences with no filler. It front-loads the free nature and the returned data, then immediately gives the critical workflow instruction. Every word earns its place.

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

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

For a zero-parameter, read-only, idempotent tool, the description covers what it returns, that it is free, and exactly when to call it. No output schema exists, but the listed data fields and the explicit sequencing before publish_intent make this complete enough for correct invocation.

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

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

The input schema is empty with zero parameters, so there are no parameter semantics for the description to clarify. The baseline for a no-parameter tool is 4, and the description appropriately adds no unnecessary parameter details.

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 enumerates what the tool provides: credit balance, at-risk bond, settled history, standing, and current cost of an intent. It also ties it to publish_intent, which helps distinguish it from sibling tools, though it lacks an explicit retrieval verb and does not name sibling alternatives.

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 instruction 'Call this before publish_intent' provides a clear, actionable usage context. It does not explicitly mention when not to use it or name alternatives, but the temporal guidance is strong and sufficient for an agent deciding to invoke it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the 'live band' detail as a content expectation, but does not go beyond that; no return format or further behavioral context is provided.

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

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

The description is a single, front-loaded sentence with no wasted words. Every part contributes meaning: 'single venue', 'by its id', and 'including its live band'.

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 one-parameter lookup with strong annotations, the description covers the essential behavior and a key content detail. It could be more complete by naming the alternative search tool or describing the return shape, but nothing critical is missing for invoking 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% for the single required place_id parameter. The description reinforces that the tool works by id but adds no additional semantic detail beyond what the schema already provides, matching the baseline.

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

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

The description states a specific verb ('get') and resource ('single venue by its id'), and also adds a distinguishing detail ('including its live band'). It is clear and distinct from siblings like find_places, though it does not explicitly name the sibling it should be chosen over.

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

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

The phrase 'by its id' implies this tool should be used when a specific venue id is already known, rather than for searching. However, it does not explicitly state when to use get_place over find_places, leaving usage 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?

The description adds meaningful behavioral details beyond the annotations: results are ordered busiest first, missing cities definitively mean not covered (closed-world semantics), and cities are always returned even when quiet so presence does not imply activity. These details are consistent with the readOnlyHint, idempotentHint, and openWorldHint=false annotations.

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

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

Three tightly written sentences, each carrying unique information: scope/ordering, coverage semantics, and the quiet-city caveat. The most important fact is front-loaded and there is 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 read-only list tool, the description plus schema and annotations cover selection criteria, ordering, coverage semantics, safety, and idempotency. No output schema exists, but the description sufficiently clarifies what the list represents and how to 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 input schema already provides 100% parameter coverage with clear descriptions for limit, country, and activity. The tool description adds nothing about these parameters beyond the general ordering 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 uses a specific verb ('list') and resource ('every city Vicinity covers'), and adds a precise ordering rule ('busiest first'). It also frames the tool as the authoritative answer to coverage questions, which distinguishes it from siblings like get_coverage and get_city_status.

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

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

The description clearly establishes when to use the tool: whenever the agent needs to answer 'is <place> covered?' It does not explicitly name alternatives or state when not to use it, but the authoritative framing gives strong contextual guidance among the sibling 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?

The description adds valuable behavioral context beyond the annotations: it discloses that only host-marked public events appear, host identity is omitted, and the look-ahead window is capped at 30 days. These are meaningful constraints an agent needs to know and are not present in the annotations.

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

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

The description is compact, with four short sentences, each conveying a distinct behavioral fact. It front-loads the core purpose ('Public events, soonest first') and avoids filler or redundant wording.

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

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

Given the tool has no output schema and 7 optional parameters fully documented in the schema, the description covers all essential behavioral aspects: ordering, visibility, host privacy, and time window. Nothing critical is missing for an agent 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?

Schema description coverage is 100%, so every parameter is already documented in the schema. The description does not elaborate on any parameter, providing no additional semantic value beyond the schema's own descriptions. This warrants the baseline score of 3.

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

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

The description clearly states the tool lists public events in chronological order ('Public events, soonest first'), which identifies the verb and resource. However, it does not explicitly distinguish itself from the sibling tool 'whats_happening', which may also relate to events, so it falls just short of a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives or any exclusions. It implies that you use it when you need public events, but there is no explicit mention of alternatives like 'whats_happening' or conditions favoring one over the other.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it reveals that the tool returns only counts, never identities ('you never learn who'), and that it is free. This is meaningful disclosure of a privacy/aggregation behavior that an agent would not infer from the schema or annotations.

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

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

Three sentences, each earning its place: the first defines the resource with concrete examples, the second states the use case, and the third discloses the critical privacy/aggregation behavior. The most important constraint ('Counts only') is front-loaded near the end but clearly separated. No 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, idempotent list tool with 100% schema coverage and no output schema, the description is nearly complete. It covers what the tool returns (counts), the use case, and the privacy limitation. The only minor gap is that it doesn't explicitly state the default city binding behavior, though the schema's 'Defaults to the bound city' covers that.

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 three parameters (city, kind, limit). The description adds the 'Counts only' semantic that clarifies what the returned data represents, but it doesn't add per-parameter meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('list'), a resource ('coordination intents'), and a scope ('in a city'), with concrete examples ('bonfire tonight', 'climbing partner'). It also explicitly frames the tool's purpose as answering 'is anyone else trying to do this?', which distinguishes it from sibling tools like list_events or whats_happening.

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

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

The description gives clear context for when to use it ('is anyone else trying to do this?') and notes a key limitation ('Counts only: you never learn who'). It doesn't explicitly name alternatives or exclusions, but the sibling list and the 'Counts only' caveat make the usage context clear enough.

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

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

With annotations indicating readOnlyHint=false, the description adds critical context: the tool is a paid operation with a non-refundable fee plus refundable bond, requires payment proof, and cannot succeed on blind retry. It also mentions that the operation is irreversible in terms of cost (non-refundable fee). This goes beyond the basic mutation flag and explains the payment and retry behavior, but it doesn't detail side effects like whether the intent becomes visible immediately or duration limits beyond 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 description is concise but packed with essential information: what the tool does, the payment requirement, the precise call flow (check payment, pay, retry), and a caution to publish only with agreement. It is front-loaded with the core purpose and the paid nature, then the procedural details. No redundant sentences; every one adds value.

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

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

Given the tool's complexity (payment, retry flow, user agreement), the description covers the essential steps: check payment status, handle payment_required, retry. It also warns about blind retries. However, it doesn't specify what the response looks like, but there is no output schema, so the agent might want to know if it returns an ID or success indicator. Also, it doesn't mention potential errors for rejected content, but the schema mentions rejection. Overall, it's fairly complete for a payment-gated publish tool.

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

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

Schema coverage is 100%, so the schema documents all parameters well. The description adds value by clarifying the payment parameter: it says to attach proof after payment, and implies the payment field is how to attach it, but it doesn't explicitly name 'payment' field. It also emphasizes the title field as 'from the user's side' and content rules, which reinforces schema. However, it doesn't add extra meaning to 'city' or 'window_minutes' beyond what schema says. Given 100% coverage, baseline is 3, but the description's hint about payment proof and retry adds a bit more, so 4 is justified.

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 verb 'publish' and the resource 'coordination intent', with specific constraints (one city, bounded window, person you act for) and the paid nature. It distinguishes from siblings like 'reciprocate_intent' and 'report_intent' by explicitly framing this as the act of announcing an intent. The title confirms it is a paid publishing action, which is unambiguous.

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

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

The description provides explicit guidance: call `get_payment_status` first, if payment is required pay then retry, and a blind retry cannot succeed. It also advises to publish only with user's agreement. This tells the agent exactly when and how to use the tool, including preconditions and payment flow, which is more than just context.

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 provide only all-false hints, so the description carries the transparency burden. It discloses that the action is free, contributes to matching and reputation, and enforces a per-agent-per-intent limit. It stops short of mentioning reversibility or error behavior, but for a simple action this is sufficient.

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

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

The description is two sentences, front-loaded with the action ('Tell another agent you want in') and followed by necessary mechanical details. Every clause earns its place; there is no filler or redundancy.

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

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

For a one-parameter tool with no output schema, the description covers the action, mechanics, and constraint well. It does not define 'enough reciprocations' or error conditions, but those are not required to invoke the tool correctly. Given the sparse annotations, the description is adequately complete.

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

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

The schema already fully documents the single parameter (intent_id as `id` from `list_intents`, 100% coverage). The description adds no additional parameter-level meaning, so the baseline score 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 starts with a clear action verb ('Tell') and specifies the resource ('another agent you want in'), making the core function obvious. It also explains the mechanism and effect (turning intents into a possible meetup, earning reputation), which distinguishes it from publish_intent and report_intent without naming them.

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

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

The description clearly implies when to use the tool: when you want to join another agent's intent. It does not explicitly name alternatives like publish_intent or report_intent, nor does it state exclusions (e.g., don't use on your own intent), but the context and sibling names make the use case apparent.

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

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

The description discloses key behavioral traits beyond the sparse annotations: it is free, rate-limited per agent, has a collective threshold effect, and captures the author's bond. It also warns against coordinated false reports, which is valuable context. No contradiction with annotations.

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

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

The description is compact and front-loaded with the purpose, then provides necessary usage constraints. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (one parameter, no output schema), the description adequately covers the trigger condition, the rate limit, the collective effect, and the consequence (bond capture). An agent has enough information to call it correctly and understand its impact.

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

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

The single parameter `intent_id` is fully documented in the schema (100% coverage) with a reference to `list_intents`. The description adds no additional parameter-specific detail, so a 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 states a clear action (flag) on a specific resource (intent) and defines the purpose as identifying spam or fabrication. It distinguishes itself from siblings like list_intents and publish_intent by focusing on reporting junk.

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 conveys when to use the tool ('when an intent looks like spam or a fabrication') and adds operational constraints (one report per agent, threshold effect). While it doesn't name alternative tools, the context is clear enough that an agent can infer when to invoke it.

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

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

Annotations already cover read-only, idempotent, non-destructive behaviorikuha. The description adds valuable behavioral context beyond that: a combined result from two sources, the use of a coordinate as an alternative center, and the explicit no-venues-and-no-events is a valid, common response. It does not fully describe parameter interaction or result shape, but the additions are meaningful.

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: 'Start here' immediately signals default use, then the return value and intent are stated in one sentence. The alternative-call guidance and empty-result warning each earn their place without any redundant wording.

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

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

The description gives the agent enough context to invoke the tool correctly: what it returns, when to prefer it, and how to interpret an empty result. With no output schema, it does not describe the response structure, but for a read-only aggregation tool with fully documented optional parameters, this is an acceptable gap. Slight missing detail around time windows or the exact relationship between city and near is outweighed by the strong overall guidance.

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 five parameters. The description reinforces that 'city' and 'coordinate' are the two possible centers, but it does not add any new semantic detail about limit, radius, or include_events. This matches the baseline for fully self-documenting schemas.

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 ('Returns') and resource ('the venues and public events around a city or a coordinate'), and clarifies this happens 'in one call'. It differentiates the tool from the relevant siblings find_places and list_events by explicitly positioning it as their combined alternative.

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

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

It opens with 'Start here', states the core use case ('is there anything on near me?'), and explicitly instructs 'Prefer this over calling find_places and list_events separately'. It also covers the important empty-result behavior, telling the agent to report a quiet city rather than an error, which removes a likely failure mode.

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