num

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 proactively mentions the quota consumption, which is a behavioral side-effect. It doesn't cover error cases or return format, but for a simple get-by-ID operation, this is reasonable.

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 short sentences, front-loaded with the core purpose ('Full record for one place by place_id') and a single additional warning. 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 is simple (one param, no output schema), and the description covers what it does and a key quota limitation. This is complete 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 coverage is 100%, and the schema already describes place_id as 'The place_id returned by num_search_places.' The description merely repeats 'by place_id' without adding extra semantics, so it doesn't exceed the baseline for well-documented 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 description clearly states the tool returns the full record for one place, identified by place_id. This distinguishes it from sibling tools like num_search_places (which searches) and num_list_submissions (which lists), 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 implies the tool is used when you already have a place_id and need the full record, contrasting with search/list alternatives. It also adds a useful quota warning ('Counts against your daily read quota') that guides cautious usage, though it doesn't explicitly mention when not to use 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?

With no annotations, the description carries the full burden. It adds the useful context that the operation is free/unmetered and that results include review decisions. However, it does not disclose pagination behavior, default response format, or how the status filter affects results beyond the schema's enum.

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 short sentences with no fluff. The cost note is slightly tangential to core functionality, but overall it is concise and front-loaded with the main purpose.

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 three optional parameters and no output schema. The description covers the main return content (submissions and reviewer decisions) and adds a cost note, but does not describe the response structure, pagination, or how status filters interact. It is adequate for a simple list tool but leaves notable gaps.

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 has 0% description coverage, and the tool description provides no clarification for limit, offset, or status. Parameter names are somewhat self-explanatory, but the description does not compensate for the missing schema descriptions, leaving ambiguity about default values and behavior.

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 it returns everything the user submitted and the reviewer's decision, which clearly differentiates it from sibling tools like num_submit_business or num_get_place. However, it lacks an explicit verb like 'list' or 'retrieve', making the purpose slightly less precise.

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?

No guidance is given on when to use this tool versus alternatives, and there are no exclusions or prerequisites mentioned. The 'Free and unmetered' note is about cost/limits, not about usage 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?

With no annotations provided, the description adds a behavioral trait: 'Counts against your daily read quota.' This is useful but incomplete; it does not disclose result ordering, return format, or how multiple filter parameters are combined (AND vs OR), which are relevant for a search operation.

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

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

One dense, front-loaded sentence delivers purpose, scope, filter requirement, and quota without redundancy. No filler words or restating of field names.

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 no output schema and simple search operation, the description covers the essential context: what it searches, how to constrain a query, and a quota limit. It does not explain return value structure, but that is likely implied for a search endpoint, and the schema already documents parameter limits.

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 covers all 5 parameters with descriptions (100% coverage), so baseline is 3. The description adds cross-parameter semantics by requiring at least one of q, city, country, or category, which is not evident from the schema's optional flags, thereby increasing clarity.

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?

Clearly states 'Search NUM's directory' with a specific verb and resource, and elaborates with scale (2.5 million places, 77 destinations, 38 countries) and categories (restaurants, bars, hotels, spas, tours, shops). This distinguishes it from sibling tools like num_get_place (get specific place) and num_submit_business (submit).

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 a concrete usage requirement: 'Give at least one of q, city, country or category.' However, it does not explicitly compare to alternatives (e.g., num_get_place) or state when not to use this search tool, so usage context is only implied.

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 of behavioral transparency. It clearly discloses that submissions are human-reviewed and never go live automatically, which is a critical behavioral trait. It also sets expectations about honesty and data accuracy. However, it does not mention the asynchronous nature (callback) or the ability to edit via external_ref, which are present in the schema but not highlighted behaviorally.

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 adding value: purpose, cost, review process, relationship disclosure, and data integrity. It is front-loaded with the core action and stays relevant without fluff. The only minor issue is that the ethical rules could be more compactly phrased, but overall it is appropriately sized.

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 tool with 15 parameters and no output schema, the description covers the review workflow and ethical usage but omits key workflow details such as the callback mechanism, the ability to edit pending submissions via external_ref, or what happens after approval/rejection. It provides a solid baseline but lacks end-to-end guidance for a moderately complex submission tool.

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

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

Schema description coverage is only 40%, so the description is expected to compensate. It provides meaningful guidance for the 'relationship' parameter by explaining the three categories, and the 'never invent contact details' rule applies to email/phone fields. However, it leaves many other undocumented parameters (e.g., hours, languages, price_range) without additional semantics, so it only partially compensates for the coverage gap.

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

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

The description opens with 'Submit a business to NUM', which clearly states the action (submit) and resource (business). It distinguishes itself from sibling tools like num_search_places and num_list_submissions by focusing on the submission action, and is distinct from num_submit_promo by specifying 'business' rather than promo. The additional context about human review further clarifies its 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 implies usage when one needs to add a business to NUM, but it does not explicitly contrast with alternatives or state when not to use it. The ethical guidelines (say honestly your relationship, don't invent contact details) are useful but are more about how to fill parameters rather than when to invoke the tool. No explicit 'use this instead of X' guidance is present.

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. It adds useful behavioral context by stating it is 'Free and unmetered' and 'reviewed by a person before it is shown to anyone,' which are non-obvious traits. It doesn't cover all side effects (e.g., idempotency via promo_ref), but offers meaningful 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, efficiently front-loading the core purpose and then adding key behavioral notes. Every sentence earns its place with no redundant or filler content.

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 mutation tool with no output schema and no annotations, the description is too thin. It covers the prerequisite (existing business) and human review but omits guidance on parameter relationships, idempotent edits, date/discount constraints, and success/error behavior. It is incomplete for an agent to reliably invoke the 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 only 50%, leaving half the parameters undocumented. The description adds minimal parameter-level meaning: it hints at 'kind' (promo/special/event/ad) and the business reference (submission_id/external_ref), but does not explain terms, detail, dates, discount, or other fields. The description does not adequately compensate for the gap.

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

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

The description clearly states the action ('Post') with a specific resource ('promotion, special, event or ad') and a qualifying context ('against a business you already submitted'), which distinguishes it from sibling tools like num_submit_business and the read 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?

The description gives clear context by requiring an already-submitted business, implicitly directing users to submit a business first (via num_submit_business). It doesn't explicitly name alternative tools or exclusions, but the prerequisite is effectively stated.

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