agora

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals important privacy protections (neither side sees contact details), the relay mechanism, the verification requirement, and the return value (threadRef). This is far more transparent than typical tool descriptions and leaves no critical behavioral aspect undocumented.

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 five sentences, each contributing a distinct, non-redundant fact: the action, delivery path, reply path, privacy, verification, and return value. It is front-loaded with the main verb and free of filler or repetition.

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

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

Given the absence of both output schema and annotations, the description covers the essential contract: purpose, privacy, verification, and how to follow up (threadRef with get_thread). The only minor gap is explicit error behavior when contacting an unverified business, but the verification statement implies this limitation.

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 each parameter already has a detailed description in the schema (e.g., id accepts ID or slug, message has content guidelines). The tool description adds behavioral context about the message channel and reply thread, which complements the schema without duplicating it. This elevates it above the baseline 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 core action: 'Send an enquiry to a business through the Agora relay.' This is a specific verb-resource pair that distinguishes it from sibling tools like get_business or request_quote. It is unambiguous what the tool does.

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 key usage context: only verified businesses can be contacted, and replies return on the same thread to be polled with get_thread. This implies when and how to use the tool, though it does not explicitly contrast it with request_quote or wait_for_reply. The guidance is adequate but not 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?

With no annotations, the description carries the transparency burden. It discloses key behavior: it returns the reference, exact hashed claim, and chain coordinates, and clarifies the verification method (chain 63868, without trusting Agora). It does not, however, specify behavior when no attestation is found or any potential error conditions, which would elevate transparency further.

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 well-structured and front-loaded with the core purpose. Every sentence adds distinct value: purpose and return values, usage guidance, and a critical trust note. It is concise despite containing substantial information, with 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-style tool with no output schema, the description is quite complete: it explains what is returned, how it should be used, and the trust model. It omits edge-case behavior (e.g., absence of attestation) and does not explicitly label itself as read-only, but these are minor gaps given the provided context.

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 provides 100% coverage of the single parameter, stating 'Business id OR slug. Both are accepted.' The description does not add any additional meaning to the parameter beyond what the schema contains, so the baseline 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 tool checks whether a business holds a current Veri5 attestation, with a specific verb and resource. It also distinguishes from siblings by detailing the unique return payload (reference, hashed claim, chain coordinates) and explicitly ties it to the attestation-checking use case.

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 offers explicit usage guidance ('Use this before telling a user a business is verified') and a strong behavioral directive ('prefer the payload’s own note...'). However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of a 5.

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

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

With no annotations provided, the description carries the burden of disclosure. It clearly states that contact details are never included, a key behavioral constraint. It also frames the tool as returning a 'public profile', implying read-only access. While it doesn't mention auth, errors, or response specifics, the disclosed limitation and public nature provide solid transparency.

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 main purpose, and every clause adds value. The first sentence names the resource and its contents; the second sentence provides a critical exclusion and directs to the alternative tool. No 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?

Even without an output schema, the description explains what the tool returns (specific profile fields) and what it intentionally excludes. For a simple retrieval tool with two input params, this is sufficient context for an agent to invoke 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%, with both 'id' and 'slug' already described in the input schema. The tool description adds no additional parameter context beyond what the schema provides, 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 'Full public profile for one business' and enumerates exactly what is included (offerings, prices, hours, area, languages, photos, verification). It also explicitly distinguishes itself from 'contact_business' by stating contact details are never included, making the purpose unambiguous and differentiating from siblings.

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 an explicit alternative: 'use contact_business to reach them' for contact details. This clarifies when to use this tool vs a specific sibling. It also implies this tool is for obtaining the full public profile, covering the primary use 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?

With no annotations, the description carries the full burden. It discloses that this is a read operation, that replies may not be immediately available, and that polling is expected. It doesn't cover error cases or auth, but adds meaningful behavioral context beyond a generic 'Get thread' title.

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 concise sentences: the first states the action and result, the second gives practical polling advice. No filler, ideas front-loaded.

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

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

For a simple single-parameter read tool without an output schema, this description covers purpose, content, and usage timing. It could mention edge cases like invalid threadRef but the polling advice covers the main asynchronous behavior.

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

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

Schema coverage is 100%; the threadRef parameter is well-documented in the schema as returned by contact_business or request_quote. The description itself doesn't add parameter details, 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?

The description states the tool reads a relayed conversation including business replies, clearly distinguishing it from siblings like contact_business (action) and search_businesses (search). The verb 'Read' and specific resource make the purpose 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 explicitly instructs to poll after contact_business and explains why (businesses reply asynchronously). It doesn't explicitly name alternatives like wait_for_reply but provides clear context for when this tool is appropriate.

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?

No annotations are provided, so the description carries the full burden. It discloses that flagging 'feeds re-verification,' implying the action does not directly edit/remove the listing but triggers a review process. However, it omits other behavioral details such as authentication requirements, idempotency, rate limits, or what happens to the listing after reporting. It is adequate but not rich.

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, front-loaded with the core action. The first sentence states what and when; the second explains the consequence. There is no wasted information or repetitive restatement 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 simple reporting tool with 3 parameters, no output schema, and no nested objects, the description provides sufficient context: the purpose, trigger conditions, and downstream effect. It lacks explicit return value information, but for a flagging tool the response is likely a simple acknowledgment. The description is complete enough for an agent to select and invoke the tool 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 67% (id and reason are described; note is not). The description adds some context by listing example reasons that map to the enum values, but it does not directly explain the 'note' parameter or provide syntax/format details. The added value is marginal beyond the schema.

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

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

The description uses a specific verb 'Flag' with a clear resource ('a listing') and scope ('wrong, unreachable, or not a real business'). It also states the purpose ('feeds re-verification and keeps the registry trustworthy'), which distinguishes it from sibling tools like get_business or search_businesses. This is a clear, action-oriented purpose.

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 explicitly lists the conditions for use: 'wrong, unreachable, or not a real business.' This tells the agent when to invoke the tool. It does not explicitly mention alternatives or exclusions, but the criteria are specific enough to avoid confusion with other tools. The downstream effect (feeds re-verification) further clarifies its role.

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 no annotations, the description steps in to disclose behavior: it requires an authorized key, returns a parsed structure (price, conditions, availability), and preserves anonymity ('Neither side sees the other’s contact details'). This provides solid transparency, though it doesn't mention potential side effects or error handling.

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 three sentences and front-loaded with the core purpose. Every sentence adds value: purpose, usage guidance, and key requirements. 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?

The tool has 8 parameters but no output schema. The description compensates by describing the nature of the reply ('parsed price, conditions and availability') and the anonymity guarantee. It doesn't detail every aspect (e.g., how to match replies with wait_for_reply), but for a structured request tool it's sufficiently 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?

Schema coverage is high at 88%, so the schema already describes most parameters (e.g., scope, budgetMaxSen, offeringId). The description adds no parameter-specific details, but it provides the overall context of a structured request. Thus the baseline 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 tool's action ('Ask a business for a price on a specific job') and its structured nature. It explicitly distinguishes this from the sibling tool contact_business, making the purpose 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 gives an explicit usage rule: 'Prefer this over contact_business whenever the customer wants a price.' It also provides a reason (parsed price, conditions, availability) and a prerequisite (authorized key), effectively guiding selection among alternatives.

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

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

With no annotations, the description carries the full transparency burden. It discloses ranking criteria (verification tier, recency, distance), the existence of verificationTier on results, and instructs not to describe unverified listings as verified. It also notes geographic coverage limitations, which is valuable behavioral context.

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 three sentences, front-loaded with the core purpose, and every sentence earns its place: definition, coverage caveat, and usage plus ranking. No fluff or repetition.

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

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

For a search tool with 7 params and no output schema, this description covers the non-obvious context: registry coverage, ranking behavior, and verificationTier caution. It doesn't describe result fields or pagination, but those are less critical given the schema details, making it quite complete overall.

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 86%, so the baseline is 3. The description adds a concrete example for query and near ('aircon repair near Bangsar') and ties distance to ranking, but mostly the schema already provides adequate parameter descriptions. It doesn't significantly add beyond that.

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: 'Search the Agora registry of verified local businesses.' It clearly distinguishes this from sibling tools like get_business by focusing on discovery by need and location, reinforced by the example 'aircon repair near Bangsar'.

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

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

It explicitly directs use: 'Use this to find a business by need and location' and provides a critical coverage guideline ('if a search returns nothing for a place, say Agora does not cover it yet'). It does not explicitly name alternatives like get_business for when an ID is known, but the use context is clear.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It explains the blocking nature (up to about a minute), that it returns the moment a reply lands, and the meaning of answered=false. It even offers interpretive guidance for the agent, which is valuable beyond the schema. This satisfies transparency very well.

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 three sentences, front-loaded with the core purpose followed by usage guidance and error interpretation. No fluff or repetition; every sentence contributes meaning.

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 there is no output schema, the description appropriately reveals the answered=false field and the semantics of a wait. However, it doesn't fully describe the return payload when answered=true (e.g., whether it includes the reply content), which is a minor gap. Still, for a simple wait tool, the description gives enough context for correct usage.

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 both parameters (threadRef, timeoutSeconds) already have clear descriptions. The tool description does not add significant new parameter semantics—it only mentions 'about a minute' which aligns with the schema's max 55. Baseline 3 is appropriate because the description doesn't need to compensate for schema gaps.

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

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

The description clearly states the tool's verb ('Hold on until') and resource ('the business answers an enquiry or quote request'), and it explicitly differentiates from sibling get_thread by recommending this over polling. This gives precise purpose and distinguishes it from 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 description explicitly instructs when to use this tool (waiting for a reply to an enquiry/quote) and provides a direct alternative comparison ('PREFER THIS over polling get_thread in a loop'). It also gives actionable guidance on handling answered=false, telling the agent to inform the user and offer to check again. This is exemplary usage guidance.

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