NUM

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 valuable behavior beyond annotations: each call counts against the daily read quota, booking.method meanings and how to act on them, the closed-status caution, and that accolades carry source and menu is owner-provided. 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 moderately long but every sentence carries functional weight. It front-loads the core purpose and then unpacks booking details and precautions in a logical order. Slightly dense but not verbose; 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?

With no output schema, the description compensates by explaining the return structure's key aspects: booking.method values, open_status.closed, accolades, and menu. It also flags the quota. It doesn't enumerate every field, but for a get-by-id tool it's sufficient for an agent to understand expectations and side effects.

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 parameters are already documented. The description adds meaning by explaining that party_size, date, and time are used to prefill the venue's booking page, and that place_id comes from num_search_places. This bridges the parameters to the booking workflow, adding value 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 clearly states the tool returns the full record for one place by place_id from num_search_places, and explicitly includes how to book it. The verb+resource (get place details) is specific, and it differentiates itself from siblings like num_search_places (search) and num_submit_* (submissions). It even details booking.method values, making the purpose unmistakable.

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 the workflow (use after num_search_places) and provides strong usage guidance: how to interpret booking.method, when to send travellers (and when not to, e.g., if open_status.closed is true), and to follow booking.guidance exactly. It doesn't explicitly name alternative tools or state when not to use this one, but the context is clear enough for an agent.

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: the price can rise mid-drop, a purchase within max_price_cents completes at the new price while a higher price returns price_moved with nothing charged, metadata is stripped, and the response flags test: true during the test run. It also notes the per-UTC-day spend cap and that the idempotency key makes retries safe, giving the agent the failure and no-charge semantics the annotations do not carry.

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 core action, then layers the price, idempotency, cap and test-mode caveats in a logical order. The sentences are long and dense but nearly every clause conveys a distinct operational rule.

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 return contract itself (license, download link, test flag, price_moved code) plus the spend cap and no-charge guarantees. An agent has everything needed to call this correctly and interpret failure modes.

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 75%, yet the description still adds real meaning: max_price_cents is framed as the operator's agreed ceiling and its behavior on price movement is spelled out, and idempotency_key's retry semantics are reinforced. The 'use' enum values (social/web/ad/ai_training) are left to the schema, which is a minor 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?

States a precise verb+resource+effect: buys one use of one photo from the account's prepaid wallet and returns a license plus a download link with metadata removed. This clearly distinguishes it from siblings like num_quote_photo and num_photo_wallet, which do not transact.

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 operating context (set max_price_cents to the operator's agreed ceiling; prices rise in a live drop) and explains the refusal path. It never explicitly names the alternative to consult first (num_quote_photo), so the when-not guidance is implied rather than routed.

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 and idempotentHint=true, so the safety profile is covered. The description adds useful context about being free, unmetered, and keyless, and specifies the scope ('every destination NUM covers'). It does not mention return format or pagination, but those are less critical given 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?

Two sentences, no fluff, with the core purpose front-loaded and the usage hint following immediately. 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 parameter-free read-only list, the description is fully sufficient. It explains what is returned (destinations with countries), how to use the results, and any access constraints (free, unmetered, no key). 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?

The tool has zero parameters, so schema coverage is 100% automatically. The description adds no parameter-specific detail, but none is needed. Per the baseline for 0 params, a 4 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 purpose: listing every destination NUM covers with its country. It distinguishes itself from siblings like num_search_places by focusing on the complete list rather than a filtered search.

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 explicit guidance on how to use the results: 'Use a destination's name or slug as num_search_places city.' It also notes that the tool is free, unmetered, and requires no key, which helps agents decide when to call 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 readOnly, idempotent, and non-destructive behavior, so the description carries a lighter burden. It adds 'Free and unmetered,' a useful cost/rate-limit behavior, and indicates the output includes reviewer decisions. It does not discuss pagination or status filtering, but annotations cover the safety profile.

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 compact sentences with no filler. The main purpose is front-loaded, and the cost/reliability note is a single short second sentence that adds value without bloating the 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 read-only list tool with no required parameters and safety annotations, the description provides sufficient context: it tells the agent what the result will contain and that it is free/unmetered. It omits response shape details, but the absence of an output schema and the simple nature of the operation keep this from being a major 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 description coverage is 0%, and the description does not explain `limit`, `offset`, or `status`. The 'reviewer's decision' phrase hints at what `status` may filter on, but there is no explicit mention of the enum values or pagination semantics, so the description fails to compensate for the missing schema descriptions.

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 ('Lists') and a clear resource ('the businesses and promotions this account has submitted') with a concrete outcome ('with the reviewer's decision on each'). This scope distinguishes it from sibling tools like num_search_places, num_get_place, and the submit tools without 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?

The phrase 'this account has submitted' clearly signals this is for retrieving one's own submissions, giving the agent a clear context in which to select it. It does not explicitly name alternatives or exclusions, but the sibling set and the resource scope make the appropriate use-case obvious 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?

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds valuable context beyond annotations: it is free and unmetered, the balance includes test credit, and it names the related topup endpoint. Minor gap: it does not describe caching, freshness, or error behavior.

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

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

Two sentences with zero waste. The first front-loads the returned data; the second covers cost model and the follow-up topup endpoint. 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 zero-parameter read tool with annotations covering safety, the description is nearly complete: it explains the return payload, cost model, and the topup alternative. There is no output schema, so return fields must be inferred from prose, but the prose enumerates them adequately.

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?

Zero parameters, so the baseline is 4. The description correctly implies no input is needed and adds semantic value by explaining what the returned fields mean (cents, test credit, daily cap, licenses) even though no output schema exists.

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

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

States a specific resource (photo wallet) and enumerates exactly what it returns: balance in US cents, test credit, today's spend against the daily cap, and held licenses. The agent knows precisely what data comes back, distinguishing it from siblings like num_license_photo or num_quote_photo.

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?

Mentions it is free and unmetered and routes to the topup endpoint for adding credit, giving clear when-to-use context. It does not explicitly contrast with sibling tools like num_quote_photo or num_license_photo, so the differentiation is implicit 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 open-world, so the safety profile is covered. The description adds genuinely new behavioral context: nothing is charged and the call counts against the daily read quota — a cost/rate constraint the agent cannot get from 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?

Two tight sentences with the useful constraint (no charge, quota impact) front-loaded. Slightly fragmentary but every element earns its place 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?

There is no output schema, so the description carries the return burden and does so by naming the two returned items (price in US cents, full license terms). Combined with the quota and no-charge notes, an agent has enough to call this correctly, though enum semantics remain unaddressed.

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%: photo_id is documented in the schema ('From num_search_photos') but the 'use' enum is not explained anywhere. The description adds no meaning about the enum values (social/web/ad/ai_training) or how they affect price, so it lands at the baseline for partial 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 resource (price and license terms for one use of one photo) with a clear scope of 'one use'. It implicitly distinguishes itself from the licensing sibling via 'Nothing is charged', but never names num_license_photo outright, leaving differentiation to inference.

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?

'Nothing is charged' implies this is a pre-purchase quote rather than a license action, which is useful routing information. However, it never explicitly states when to use this versus num_license_photo, nor mentions prerequisites beyond a note about quota.

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 safety (readOnly, idempotent, non-destructive, openWorld), yet the description adds substantial non-obvious behavior: the live-drop license mechanism with 10% price escalation and 3-day window, null price meaning a use is unavailable, the human review and no-coordinate/no-exact-date privacy guarantees, and that each call consumes the daily read quota. This is well beyond what structured fields 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?

Front-loaded with purpose, then moves to result shape, pricing, drops, and caveats — logical order with little wasted text. It is dense and runs long for a search tool, and the pricing/drop sentences could be tightened, but each sentence carries 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?

With no output schema, the description fully carries the burden of describing returns (photo_id, preview URL, place breakdown, month, photographer, per-use prices) as well as the quota cost. An agent has everything needed to interpret results without opening a 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 63% and the description adds real meaning: it explains why 'use' exists (pricing per use type), what ai_training actually filters on (photographer permission), and links place_id back to num_search_places. It does not clarify kind, limit, or offset beyond the schema, keeping it 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?

Opens with a specific verb+resource+scope: 'Search photos of real places taken by NUM travelers and offered for licensing per use.' This clearly separates it from the sibling num_search_places (places vs. photos) and from num_license_photo (search vs. purchase).

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 the licensing framing and the place_id reference to num_search_places, but there is no explicit when-to-use/when-not or routing to the obvious follow-on siblings (num_license_photo, num_quote_photo). The agent must infer the search-then-license workflow.

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 mark the operation read-only, open-world, idempotent, and non-destructive. The description adds meaningful behavioral context beyond those: closed places are never returned, each call counts against the daily read quota, and it enumerates the exact fields returned, compensating for the lack of an output 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 dense but well organized: scope, how to search, a filtering caveat, return contents, next-step routing, and quota impact are each covered in compact sentences. No words are wasted and the most important information is 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 search tool with no output schema, the description is remarkably complete: it covers data scope, required location inputs, narrowing parameters, closed-place behavior, return fields, the follow-up tool, and quota impact. The limit parameter is fully documented in the schema, so its absence from the description is not a 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?

The input schema already provides 100% coverage for all six parameters with clear descriptions. The main text reinforces the relationship between city and country and describes q/area/category as narrowing filters, but it does not add substantial parameter semantics beyond what the schema already states, 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 searches NUM's travel directory of places, names the categories included, and differentiates it from siblings by pointing to num_get_place for booking and num_list_destinations for valid city choices. The verb 'search' plus the explicit resource leaves no ambiguity about what this 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?

It gives a concrete usage recipe: specify a city or country first, then narrow with q, area, and category. It also routes the agent to relevant siblings, though it does not explicitly state when to avoid this tool in favor of submission-oriented siblings, which are clearly different actions.

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 indicate destructiveHint=true, and the description justifies this by stating it creates a pending review, not an immediate listing, and warns about rejection for derived contacts. It also discloses the human review step and idempotency behavior, providing rich context beyond annotations. 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 concise and front-loaded, with the core purpose and immediate outcome stated first. It includes multiple key behavioral notes in a compact form without redundancy. Every sentence adds value, and it avoids extraneous detail.

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 (15 params, human review, idempotency) and lack of output schema, the description provides sufficient context: the review process, the 'pending_review' status, the relationship verification, the contact requirement, and the idempotent update behavior. This is enough for an agent to call correctly and set expectations.

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%, but the description compensates for several critical parameters: 'relationship' is explained (owner/agent/third party), 'external_ref' is explained (idempotency), and contact details (email, phone) are covered by the 'published' requirement. However, many other params (city, name, vertical, etc.) rely on the schema's brief descriptions, so the description adds value but isn't exhaustive.

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 action (submit a business), the resource (NUM), and the key behavior (goes to human review, never immediate). It also distinguishes itself from sibling tools by mentioning its asynchronous nature and idempotency via external_ref, unlike get/list/search which are read-only and submit_promo which is for promotions.

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 states when to use this tool (submit a business for review) and provides important exclusions: submissions with guessed contact details are rejected, contact must be published. It also clarifies idempotent behavior with external_ref, which guides proper usage. It implicitly differentiates from read-only siblings and the promo tool, though not explicitly naming them.

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 context beyond the annotations: it is free and unmetered, a human reviews it before publication, and re-sending the same promo_ref updates the pending promotion rather than creating a duplicate. These are real behavioral traits not expressed by the annotations, and the conditional idempotency via promo_ref does not directly contradict idempotentHint=false.

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

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

The description is compact and front-loaded: the first sentence states the core operation, the second adds cost/cost context, and the third explains the review and idempotent update behavior. 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 mutation-oriented tool with no output schema, the description covers the key prerequisites, review latency, and update semantics. Remaining gaps are mostly about return values and less central parameters, but the invocation path is clear enough for an agent to use 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 50%, and the description helps clarify the meaning of kind, the business linkage, and the promo_ref update behavior. However, it adds nothing about terms, detail, discount_pct, starts_at, or ends_at, so it does not fully compensate for the parameters left undocumented in 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 clearly states a specific action: attach a promotion, special, event, or ad to a previously submitted business. This distinguishes it from the sibling num_submit_business, which must be called first to create the business.

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 a clear precondition: the business must already have been submitted by the same account. It does not name alternative tools or explicitly say when not to use it, but the context of attaching to an existing submission is enough for an agent to route correctly.

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