GigNGo Local Services Marketplace

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to restate those. It adds useful behavioral detail: coordinates are privacy-offset, the 'details' field is usually the most specific part, and it lists the exact fields returned. This goes beyond annotations and helps the agent anticipate output.

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?

A single, dense paragraph that front-loads the purpose, then lists returned fields, filters, and sorting in a logical order. Every sentence contributes value; no filler. Slightly long but appropriate given the richness of the 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 fully enumerates the return fields (title, description, details, category, budget, location, timestamps, applicant counts, link) and explains default behavior (no arguments returns nationwide recent tasks). It also covers all filters and sort options, making the tool fully understandable without needing additional documentation.

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 all seven parameters are documented in the input schema. The description adds semantic nuance beyond the schema, such as explaining that 'oldest' surfaces jobs about to be abandoned and 'most_applicants' shows where locals compete, which aids correct selection.

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 ('Browse') and resource ('open jobs homeowners have posted on GigNGo') and clearly differentiates from siblings like search_local_workers (workers vs. tasks) and get_platform_info. It also enumerates the data fields, filters, and sorting, leaving no doubt about 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?

Provides clear context on how to call the tool ('All filters are optional — call with no arguments for the most recent open tasks nationwide') and explains the meaning of sort options like 'oldest' and 'most_applicants'. It does not explicitly name alternatives or say when not to use it, but the sibling set makes the distinction obvious.

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 the read-only, idempotent, non-destructive profile; the description adds meaningful scope context ('public locals', 30 categories, count per service) and clarifies state-level vs city-level behavior. 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?

Three concise sentences with no filler. The core function is front-loaded, followed by usage context and parameter guidance.

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 two-parameter read-only lookup with no output schema, the description tells the agent what it returns (service categories with counts) and exactly how to invoke it. 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?

Schema coverage is 100% and the schema already documents lowercase/hyphen formatting and the city's optional nature. The description reinforces 'state is required' and 'omit city for state-level availability' but does not meaningfully extend 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?

States a specific verb ('Check'), a precise scope ('which of the 30 service categories have public locals in a US state or city'), and an output feature ('with a count per service'). This clearly differentiates it from siblings like list_service_categories and search_local_workers.

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 a concrete usage context: 'Useful before searching' and an example question it answers ('can I get X done in Y?'). It does not name the specific alternative tool or state when not to use it, so it falls short of full exclusion guidance.

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 include idempotentHint=true and destructiveHint=false, but the description adds significant behavioral detail: it does not post on behalf, runs the draft through screening screens, and returns failure reasons if the draft is vague, advert-like, or matches scam patterns. This goes beyond the structured annotations by explaining the internal validation process and the exact nature of the output (a reviewable link or reason). 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 longer than a single sentence but every clause serves a purpose: it states the action, the non-action, the screening behavior, and the input guideline. It is front-loaded with the core benefit (drafting and returning a link) and then adds crucial nuances. While it could be tightened slightly, the structure is logical and no filler exists.

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 no output schema, the description effectively describes the return value (a link the homeowner opens, or a reason for failure) and the behavioral constraints. It covers the essential context an agent needs: what to provide (job description), what the tool will not do (post), and what happens during screening. Given the complexity of the screening process, the description is remarkably 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 100%, so all parameters have descriptions. The description adds extra semantic guidance for the 'description' parameter, instructing the agent to describe the job 'in the homeowner's own words: what needs doing, where on the property, and roughly how big.' This enriches the schema's terse requirement ('The job in the homeowner's words') with practical content expectations. The other parameters are adequately covered by the schema, so this is a modest bonus above 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 clearly states the primary action ('Draft a job post for a homeowner') and its outcome ('get back a link THEY open to review and post it'). It also clarifies what it does NOT do ('never posts on anyone's behalf'), distinguishing it from sibling tools that are primarily read/browse operations. The resource and verb are specific, leaving no ambiguity about the tool's function.

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 context on when to use this tool: to draft a job post that the homeowner will later post, emphasizing that it does not actually publish. It implies that this is the appropriate tool for drafting rather than posting directly. However, it does not explicitly name alternatives or state conditions under which another tool should be chosen, though the sibling list shows no competing drafting tool. The guidance is clear 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?

Annotations already declare readOnlyHint and idempotentHint, but the description adds meaningful behavioral context: clips are quality-checked ('Every clip was checked to show someone actually doing the work'), the platform runs no background checks (important for privacy expectations), and the ordering logic based on city/state is disclosed. These details go beyond the annotations and help the agent understand what to expect from results.

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 front-loaded with the core purpose, then efficiently lists return fields, ordering behavior, and a critical caveat about background checks. Each sentence earns its place; there is no redundant fluff. While it is longer than some, the density of useful information is high, making it appropriately structured.

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?

Since there is no output schema, the description compensates by enumerating the returned data (watch page URL, embed URL, first name, town, search words, profile). It also covers the ordering behavior and the platform's stance on background checks. For a read-only tool with four parameters, this is comprehensive enough for an agent to call it correctly without additional assumptions.

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 with descriptions for all four parameters. The tool description adds an extra layer of meaning, particularly for city and state: it explains how these parameters affect the ranking of clips (town-first, then state, then elsewhere), which is not in the schema. This richer contextual understanding of parameters justifies a score 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 states a specific verb and resource: 'Find short videos of locals doing a kind of job' with concrete examples like 'deck building' and 'pressure washing'. This clearly distinguishes it from sibling tools like search_local_workers or get_work_record, which focus on people or records rather than video clips. The purpose is unambiguous and actionable.

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. It does not state conditions that favor find_work_clips over other tools, nor does it mention any exclusions or contexts where another tool would be more appropriate. The only usage-related hint is the optional city/state filtering, which is more about parameter behavior than tool selection.

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 readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: the heat score is 'shrunk toward the platform average so a single lucky job cannot outrank a real market,' and advises reading 'heat' next to 'confidence.' This goes beyond the annotations and helps the agent interpret results safely.

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 metrics, then usage guidance, then sibling differentiation. Every sentence earns its place with no redundancy or fluff.

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 explain what is returned—it does, listing the metrics and the heat score. It also covers how to interpret the data (dense supply vs. supply holes) and provides enough context for correct invocation. Combined with the sibling reference, it is complete for an agent to use 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 covers 100% of parameters, so baseline is 3. The description adds value by explaining the 'openUnanswered' sort surfaces supply holes and suggesting minJobs=5+ for established markets. These details enrich parameter meaning beyond the schema's basic 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 clearly states the tool finds US cities and their job-market activity metrics (posts, applications, response share, median hours). It names the specific resource and distinguishes itself from check_service_availability, making its 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?

It explicitly states when to use this tool: 'Use this to decide where supply is dense (spend more) versus where jobs go unanswered (a supply hole).' It also differentiates from a sibling by noting check_service_availability counts locals rather than measuring response. It doesn't list explicit exclusions, but the guidance is strong and contextually sufficient.

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. The description adds value by specifying what content is included (limits, category counts, app links, documentation URLs) and explicitly notes the tool covers what GigNGo 'does not do (limits)', which is additional behavioral context beyond the annotations. No contradiction.

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?

A single, front-loaded sentence with a colon-delimited list. Each listed item (limits, category count, job routing, app links, API URLs) is distinct and contributes value, and the usage note is appended without repetition or fluff.

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 informational tool with no output schema, the description fully covers what the agent needs: the purpose, the content envelope, and the trigger scenario. Sibling tools are all action-oriented or data-specific, so there is no ambiguity about when this tool is appropriate.

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 parametershare, so the baseline is 4. The description correctly adds no parameter information because none exists; there is nothing more the schema or description could clarify.

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 ('Get an overview') and resource ('GigNGo'), then enumerates exact content: limits, service category count, how jobs reach locals, app links, and API doc URLs. It ends by tying it to general 'what is GigNGo' questions, which distinguishes it clearly from siblings like list_service_categories or search_local_workers.

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 says 'Call this for general "what is GigNGo" questions,' giving a clear when-to-use condition. It does not name alternatives or provide exclusion criteria, but for a zero-parameter informational tool this is sufficient context to route an agent correctly.

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, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations by listing the exact fields returned, including the `limits` field and the notable fact that GigNGo runs no background checks.

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 dense sentences with no filler. The core action and resource are front-loaded, the return contents are listed compactly, and the slug-sourcing guidance 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?

Complete for a simple read-by-slug tool. With one required parameter, no output schema, and a thorough enumeration of return fields plus notes on data provenance and limitations, an agent has enough context to invoke this 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%, so the baseline is 3. The description adds value beyond the schema by explaining where a valid slug comes from: the 'slug' field on search_local_workers results or a gigngo.org/worker-profile/{slug} URL, which helps agents source the parameter correctly.

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 and resource: 'Get the public profile of one GigNGo local by their profile slug.' It clearly enumerates what the profile contains and is naturally distinguished from sibling tools like search_local_workers, which finds locals rather than reading one profile.

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?

Implies clear usage context: call this tool when you already have a slug, which can come from search_local_workers results or from a gigngo.org profile URL. It does not explicitly list when-not-to-use or alternatives, but the workflow prerequisite is stated clearly enough for an agent to choose correctly.

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?

Beyond the annotations of readOnly and idempotent, the description discloses important behavioral limitations: GigNGo runs no background checks, filmed evidence does not prove identity, inferred_from_messages means the job was counted, and the record should never be reduced to a single score. This materially changes how an agent should interpret and use the result.

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 purpose is front-loaded, and every sentence carries essential information: what the record is, what evidence types mean, how to interpret them, usage restrictions, and how to obtain the handle. Despite its length, there is no filler or redundant restatement of the schema.

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 rich annotations but no output schema, the description is impressively complete. It explains the meaning and provenance of evidence types, warns against misuse, and tells the agent where to source the handle. Nothing critical to selecting and invoking the tool correctly 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 input schema already fully documents the handle parameter with an example, so the baseline is 3. The description adds value by explaining that the handle should be the slug from search_local_workers or get_worker_profile, which clarifies where a valid value comes from and disambiguates the expected format.

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: 'Get a local's Work Record: evidence of their work.' It explains what the record contains and enumerates evidence types, which clearly sets it apart from profile or search tools. It does not explicitly contrast itself with get_worker_profile, so it stops short of full sibling differentiation.

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 the tool—reading work evidence—and explicit prohibitions: 'Not for employment, credit, insurance or tenancy decisions.' It also tells the agent to use the slug from search_local_workers or get_worker_profile as the handle. It doesn't name an alternative tool for profile-only needs, so it lacks an explicit when-not/alternative comparison.

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, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds that it lists 'all 30' categories and includes slug examples, which is behavioral context beyond the annotations. It doesn't elaborate on the exact output structure, but that is minor for a simple read-only list.

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 no filler. The first sentence states the action and provides examples; the second sentence gives the use case. It is front-loaded with the core purpose and immediately useful to an agent.

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 simplicity of the tool (no parameters, no output schema), the description provides sufficient context: it lists what is returned (categories and slugs), gives examples, and explains the purpose in relation to other tools. An agent can call it correctly and interpret the result without further clarification.

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 and zero required parameters, so the description has nothing to add to parameter semantics. Per the baseline, a tool with no parameters receives a 4 because the description appropriately focuses on the purpose and output rather than parameter details, and it even explains how this tool's output feeds into other tools' 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 verb 'list' and the resource 'GigNGo service categories' with their slugs, providing concrete examples like 'house-cleaning' and 'electrician'. It distinguishes itself from sibling tools by explicitly framing its purpose as discovering valid values for parameters of other tools, making it 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?

It explicitly directs the agent when to use this tool: 'Call this to discover valid values for the `service` parameter of search_local_workers and the `category` parameter of browse_open_tasks.' This names the specific sibling tools and the parameters they require, leaving no ambiguity about when this tool is the right choice.

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 non-destructive behavior, and the description adds meaningful behavioral details: result ordering, the 'in', 'serves', or 'nearby' relation with miles, self-reported badges, and pagination behavior. 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 dense but every sentence earns its place: purpose, return fields, ordering rules, caveat, parameter format, and pagination. It is front-loaded and appropriately structured for an agent to parse quickly.

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 compensates well by enumerating the returned fields (name, bio, skills, prices, reviews, filmedTheirWork, workVideoCount, neighbor vouches, service area, profile URL). It also covers ordering, pagination, and a routing hint to list_service_categories, making it complete 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 already covers 100% of parameters, and the description reinforces the state/city slug format and service slug examples. It adds value by explaining how the city parameter affects ordering (area page locals first) and by describing the limit pagination behavior beyond the schema's basic range.

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: 'Find locals on GigNGo by service and place.' It clearly distinguishes itself from siblings like browse_open_tasks and get_worker_profile by focusing on searching public local profiles by service and location.

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 about when to use this tool and explicitly names list_service_categories as a precursor when unsure about the service slug. It doesn't explicitly contrast with get_worker_profile or browse_open_tasks, but the intended use case is clear enough.

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