Arranged — Curated Wedding & Event Venue Marketplace

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

Beyond the annotations it discloses concrete operational traits: strictly read-only and idempotent with zero state mutation, public unauthenticated access, and a specific rate limit of 60 requests/min per IP. It also sketches the return payload (status, records/metrics, canonical action URLs), which matters since no output schema exists.

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

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

Purpose is front-loaded and the size is acceptable, but several clauses are filler or templated: 'when you specifically need to execute check_quote_status', 'for their respective operations', and 'matched records or computed metrics' reads as boilerplate that doesn't fit a status lookup. Trimming these would sharpen the definition without losing information.

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

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

For a single-parameter read-only tool with full annotation coverage, the description supplies what's missing: access model, rate limits, idempotency, and a rough return shape. The only soft spot is the vague, possibly templated return description and the absence of any mention of what non-happy-path statuses (pending/expired token) look like.

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 schema already documents the 'cqt_...' token format and required constraint. The description only restates that clientToken is required, adding no new meaning about where the token comes from or what happens with an invalid/expired token, so the baseline 3 applies.

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

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

The first sentence names a specific verb ('check'), resource ('quote request'), scope constraint ('existing 3-venue'), and the key input ('client token'), which is enough to distinguish it from find_venues and request_curated_quotes. It stops short of 5 because the differentiation is partly carried by a generic boilerplate clause rather than by describing the actual relationship to the sibling tools.

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 names when-not-to-use cases and lists the three alternatives (find_venues, get_venue_details, request_curated_quotes). However, the guidance 'use ... for their respective operations' is vacuous and the 'when to use' clause is circular ('call this tool when you need to execute check_quote_status'), so the agent still has to infer the real selection rule (after quotes have been requested).

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 bar is lower; the description still adds genuinely new context: no authentication required and a 60 requests/min per-IP rate limit. It also caps expectations at 10 results and notes ratings are unedited, which is useful trust 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?

Scope and filters are front-loaded in a strong opening sentence, but the 'when to use' sentence is boilerplate that repeats the tool name and host rather than adding information. The trailing 'Returns: Structured JSON object containing status, matched records or computed metrics' is generic template filler for a venue search.

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 what comes back (up to 10 venues with ratings, pricing, and action URLs) plus zero-auth and rate-limit constraints. The only real gap is pagination/truncation behavior when more than 10 venues match.

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% with units, enums and worked examples for every parameter, so the schema carries the semantic load. The description only restates parameter names and optionality, adding no format or defaulting detail beyond what the schema already 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 uses a specific verb+resource ('Search and filter verified Gauteng event and celebration venues') and enumerates the filter dimensions and result shape. It explicitly distinguishes itself from siblings by naming 'get_venue_details', 'request_curated_quotes', and 'check_quote_status' as separate operations.

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

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

It states when to use and when not to use, and points to three named alternatives. However, the routing sentence is generic ('use ... for their respective operations') and never states the actual condition that selects a sibling, so the agent must infer when a quote request beats a search.

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 openWorld, so repeating 'zero state mutation' earns little. The description does add genuinely new operational context: public unauthenticated access and a rate limit of 60 requests/min per IP, both of which an agent needs before looping calls.

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 front-loaded field list is good, but the boilerplate 'When to use: ... execute <tool name>' sentence is wasted space and the Returns block ('status, matched records or computed metrics, and canonical action URLs') reads as template text not tailored to this tool.

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

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

With no output schema the description must cover return shape, and it does so only generically. It also leaves unexplained what happens when both lookup keys are omitted, which is the most likely agent confusion given both parameters are optional and the schema hints at a 'server default filter'.

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 slug and venueId are fully documented with examples in the schema. The description only restates that they are optional and adds no disambiguation of precedence when both are supplied or what the 'server default filter' means for a details lookup.

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 (retrieve) and resource (venue details) and enumerates the fields returned (amenities, star rating, capacity, pricing, contact coordinates), plus the lookup keys (slug or ID). It names the sibling tools it is not, though the differentiation is by name only rather than by capability.

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 'When to use' sentence is circular — 'call this tool when you specifically need to execute get_venue_details' — and adds nothing. The exclusion list (find_venues, request_curated_quotes, check_quote_status) is real routing value, but 'for their respective operations' never states the condition that picks one over 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?

Adds substantial context beyond the annotations: outbound email/WhatsApp notifications to venue coordinators, creation of a backend record and escrow quote review session, no auth required, and a 60 req/min per-IP rate limit. These are exactly the side effects an agent needs. The closing 'Returns: ... matched records or computed metrics' sentence is generic boilerplate and does not mention that repeats at idempotentHint=false will create duplicate sessions, keeping it below 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?

Front-loaded with the strongest sentence first, but it carries clear filler: the tautological 'When to use' sentence and a generic 'Returns: Structured JSON object containing status, matched records or computed metrics' line that adds nothing after the specific review URL was already given. The parameter roster duplicates the schema verbatim.

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 10-parameter, non-idempotent mutation with no output schema, the description covers the important operational facts: what gets created, who is notified externally, auth requirements, and rate limits. What is missing is duplicate-submission behavior and the meaning of the returned URL lifecycle (e.g., token expiry), a minor gap given no output 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 100%, so the schema already documents all 10 parameters including enums and required markers. The description merely re-lists parameter names with required/optional tags and adds no formatting or semantic detail (e.g., ZAR units, date/null interaction with dateFlexible) beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 concrete verb and resource: submitting a consolidated rate & availability request for up to 3 shortlisted Gauteng venues, and it names the concrete outcomes (coordinator alerts, escrow quote review session, review URL). It is distinguishable from check_quote_status and find_venues, though the sibling routing sentence is templated ('for their respective operations') rather than explaining the actual difference.

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 'When to use' sentence is near-tautological ('call this tool when you specifically need to execute request_curated_quotes'), which gives no real trigger condition. The 'Do NOT use' clause at least names alternatives, but does not say which conditions select them. Usage is implied by the venueIds cap of 3 and the pre-requisite of a shortlist, not stated.

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

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

Annotations already cover read-only, idempotent, non-destructive, and open-world, so the bar is lower. The description still adds genuinely new operational facts: a 60 requests/min per IP rate limit and that public unauthenticated access is permitted — both material to how an agent should call it.

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 purpose and rate limit are front-loaded, but several clauses are pure filler: 'when you specifically need to execute whoami' repeats the name, and 'for their respective operations' carries no information. For a zero-argument identity call, roughly ninety words is more than it needs.

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

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

Annotations and a trivial schema mean little is required, and the rate-limit/auth details help. But the return description ('matched records or computed metrics, and canonical action URLs') reads as boilerplate that does not fit an identity endpoint, and the tension between 'authenticated profile' and 'public unauthenticated access allowed' is left unexplained.

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

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

With zero parameters, the baseline is 4. The description correctly confirms 'zero-argument query', matching the empty schema, and introduces no phantom parameters.

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 opening sentence gives a specific verb and resource: 'Return authenticated profile or environment identity for the Arranged platform,' which an agent can act on. It also names the sibling tools it is not for, though the differentiation is by exclusion listing rather than by explaining how identity retrieval relates to the venue/quote tools.

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

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

There is an explicit 'When to use' / 'Do NOT use' scaffold with named alternatives, which is structurally more than most descriptions offer. However, the selection condition is circular ('call this tool when you specifically need to execute whoami') and the exclusion clause is vacuous ('for their respective operations'), so an agent gets no real rule for choosing this tool over just reading the schema.

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