Home-Services Agent Network

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

No annotations are provided, so the description carries the full burden. It does disclose a real behavioral trait beyond the schema: authentication via listing_key and the failure mode ('A wrong key is rejected'). It does not say whether reading marks requests as seen, whether results are paginated, or what the requests contain — meaningful gaps for an inbox tool with zero annotation coverage.

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 short sentences, front-loaded with the purpose before the credential requirements. Little waste, though the 'For a pro's agent' preamble is slightly awkward phrasing for what is essentially an audience constraint.

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 and no annotations, the description should describe what comes back — the shape of a job request, ordering, and whether the inbox is drained on read. It covers purpose and auth adequately but leaves the return contract entirely unspecified.

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%: listing_key is documented in the schema, listing_id is not. The description partially compensates by saying both values are 'issued at registration,' which tells the agent where to obtain listing_id, but it adds no format or scoping detail beyond that.

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

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

States a specific verb and resource: 'read the job requests stored in the listing's hosted inbox.' The audience qualifier ('For a pro's agent') and the inbox framing make it distinguishable from siblings like send_job_request and update_request_status, though the differentiation is implicit rather than named.

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 'For a pro's agent' framing implies who calls it and in what role, and the required credentials signal a post-registration workflow. However, there is no explicit when-to-use guidance, no mention of polling cadence, and no statement about when to prefer a sibling tool such as get_listing.

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 still adds real behavioral context: no API key is required and sensitive fields (keys, personal contacts) are never returned. It does not cover behavior on an invalid/unknown listing_id or describe the shape of the returned 'full public details'.

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 sentence, front-loaded with the action and parameter, with a compact parenthetical for the auth and privacy caveats. Nothing is wasted.

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 one-parameter read with no output schema, the auth and privacy disclosure is the key addition and it is present. However, 'full public details' is left undefined, so an agent cannot anticipate what fields come back.

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 single listing_id is already documented with its provenance. The description only restates 'by listing_id' and adds no format, validation, or sourcing detail 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?

States a specific verb and resource: fetch the full public details of a single listing, keyed by listing_id. The scope ('one listing') implicitly separates it from the plural search_pros, though no sibling is named explicitly.

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 only implied: the listing_id comes from register_business or search_pros (per the schema), so this is the follow-up detail fetch. The description itself offers no explicit when-to-use, when-not, or alternative routing.

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, and it does disclose one meaningful trait: 'counts only, no personal data', which tells the agent results are aggregated and safe to surface. It says nothing about permissions, rate limits, data freshness, or caching, which matters for a stats endpoint an agent may poll.

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, zero filler: the first front-loads the privacy guarantee and enumerates the returned metrics, the second gives the use case. Nothing could be removed 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?

There is no output schema, but the description effectively substitutes for one by listing every metric returned, including the verified/unverified split and the status breakdown for job requests. The only gap is the response shape (field names, whether counts are nested), which an agent must discover by calling.

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 takes zero parameters and the schema is an empty object, so there is nothing to disambiguate; the baseline of 4 applies. The description adds no parameter-level noise.

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 ('Counts') and enumerates exactly what is counted: total listings (verified/unverified), total searches, total job requests by status, and recent timestamps. This clearly separates it from the action-oriented siblings (get_listing, search_pros, send_job_request), though it never names them explicitly.

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?

'Use this to check whether the network is being used' gives a concrete selection context, and no sibling offers aggregate metrics, so the choice is unambiguous in practice. It does not state when not to use it or what to use for per-record inspection.

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 and does well: it discloses that new listings start unverified, that request routing can go to an external endpoint while a copy stays in the hosted inbox, that listing_id/listing_key must be persisted for check_inbox and update_request_status, and the no-prices policy. It omits auth requirements, idempotency/duplicate behavior, and any mutation-confirmation semantics.

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 action and purpose, then the input expectations, then routing behavior, then return values and the price constraint — a logical order with no filler sentences. It runs long, but nearly every clause carries operational 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?

There is no output schema, and the description compensates by naming the returned listing_id and listing_key and what they are for. For an unannotated mutation tool it covers the essentials; only auth/permission posture and duplicate-registration behavior are left unstated.

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, but the description adds real meaning beyond the schema for endpoint_url (routing behavior and hosted-inbox fallback) and frames the required set (name, trade, services, service area, hours, rules) in operational terms. It also imposes a constraint on field content (no prices) that the schema does not encode.

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 ("Register a local home-services business in the network") plus the downstream purpose (homeowner agents find it and send job requests). This is clearly distinguishable from siblings like search_pros, get_listing, and check_inbox without opening any schema.

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?

Explains the key usage decision — pass endpoint_url only if the business has its own agent endpoint, otherwise the network hosts the inbox — and warns never to include prices. It gives clear context but no explicit exclusions or duplicate-handling guidance (e.g. what to do if the business is already registered).

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 and does add useful behavior: verified listings are ranked first, listings have rules that must be respected, and the network carries no prices. It still omits other operational traits such as result limits, pagination, authentication needs, or return structure, so transparency is only moderate.

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 four short sentences and front-loads the core search action and filters. The later sentences about verified ordering, listing rules, and no prices each add relevant context without waste.

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

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

For a search tool with complete parameter schema coverage and no output schema, the description covers purpose, ranking behavior, a key limitation (no prices), and the next-step workflow around listing rules. It could be more complete by explaining result shape or pagination, but the essentials for invoking it correctly are present.

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

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

Schema description coverage is 100%, so the schema already documents trade, service, and location. The description mirrors that meaning by saying trade and city-or-ZIP location plus an optional service keyword, but adds no deeper syntax, taxonomy, or format details 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 states a specific verb and resource: search the network registry for local home-services pros, filtered by trade and location with an optional service keyword. It is clearly a search/discovery tool rather than a request-sending or listing-detail tool, though it does not explicitly name sibling alternatives to differentiate itself.

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 workflow note to read each listing's rules before sending a request, which suggests this tool is used before send_job_request. However, it does not explicitly say when to use search_pros versus get_listing, network_stats, or other siblings, nor does it give when-not-to-use 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?

With no annotations, the description carries the whole burden and does substantial work: it discloses routing to the pro's endpoint when available, guaranteed persistence in the hosted inbox and receipts ledger, and the anti-quote design (no price field). It still omits auth/identity expectations, duplicate-request behavior, and failure modes for a write 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?

Front-loaded with purpose and required fields, then constraints, then routing behavior — a sensible order with no filler sentences. The required/optional enumeration partly duplicates the schema and crowds out the more distinctive behavioral notes, costing a point.

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 9-parameter unannotated write tool with no output schema, the description covers inputs, constraints, and side effects well. It does not mention what is returned (e.g. a request ID that sibling update_request_status would need), which is the main remaining gap an agent would hit on the next turn.

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 44%, so the description must compensate, and it does by enumerating all eight required fields plus access_notes and calling out the absence of a price field — important because additionalProperties is false, so an agent that invents a price/quote field would be rejected. It adds little semantic depth beyond field names (e.g. what listing_id must reference), which keeps it from 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?

States a specific verb and resource ('Send a structured job request to a pro') plus the mechanism ('the network's standard form'), and the sibling pointers (search_pros / get_listing) locate it in a workflow rather than leaving it ambiguous. An agent can distinguish it from check_inbox or update_request_status without opening any schema.

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 prerequisite chain — 'Follow the listing's rules (see search_pros / get_listing)' — which tells the agent to resolve a listing first. It does not state an explicit 'do not use when' or what to do if required fields are unknown, so it stops short of full routing 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that this is a mutation whose changes are appended to a receipts ledger, but it omits permission requirements, reversibility, status-transition rules, and response 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 are front-loaded with the actor, purpose, status enum, required identifiers, and audit behavior. There is no redundant or filler text.

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 tool with no annotations, no output schema, four required parameters, and zero schema descriptions, the description is too thin. It leaves request_id semantics, auth requirements, transition constraints, and result behavior unspecified.

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%, so the description must compensate for all four parameters. It names listing_id and listing_key and enumerates new_status values, but it completely omits request_id and gives no deeper meaning for listing_key, leaving a required parameter undocumented.

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 ('update') and resource ('job request's status'), enumerates allowed statuses, and scopes the tool to a pro's agent. It does not explicitly differentiate itself from sibling tools, so it stops short of a 5.

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 'For a pro's agent' and the required listing identifiers imply the intended context, but the description gives no explicit when-not conditions or alternatives such as send_job_request. Usage is therefore implied rather than clearly specified.

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