Tradehand

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the domain note about instant quotes but says nothing about pagination semantics despite limit/cursor existing. With annotations carrying the safety bar, this is adequate but thin.

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 and zero padding. The trailing quote sentence is arguably tangential to invoking the tool, keeping it just below maximum.

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?

An output schema exists, so return values needn't be described, and annotations cover the safety profile. However, the tool exposes a cursor/limit pagination surface and a query filter that are entirely undocumented anywhere, leaving the agent to guess their meaning.

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% across all three parameters (limit, query, cursor), so the description carries the full burden of explaining them. It adds nothing: no mention of what query filters on, how cursor pagination works, or that limit is capped at 20.

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: 'List Tradehand's canonical UK trades.' An agent understands this returns a catalogue of trade categories. It does not, however, differentiate itself from the sibling search_traders or explain what 'canonical' excludes.

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 second sentence ('Instant quote is available before a trader is assigned') is a domain fact, not guidance on when to call this tool versus get_service_options or search_traders. No conditions, prerequisites, or exclusions are given for using browse_trades.

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 openWorldHint=false, so safety is covered. The description adds value by enumerating the returned content types (endpoints, policy, canonical URLs), but says nothing about format, auth requirements, or caching/rate 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?

A single front-loaded sentence with no filler; the verb and returned resources come first and every clause adds 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 carries the return-value burden and does list the three content categories returned, which is reasonable for a simple zero-param read tool. It could say more about the shape or purpose of these discovery artifacts, but nothing essential is missing for 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 tool takes zero parameters, so the baseline of 4 applies. The schema has no parameters to document, and the description correctly describes an argument-free retrieval.

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 names a specific verb ('Return') and concrete resources ('public agent discovery endpoints, content policy, and canonical URLs'), which clearly separates it from siblings like browse_trades, get_trader, or read_okf_concept. It is clear about what the tool produces, though it doesn't explicitly contrast itself with any sibling.

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

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

There is no guidance on when to call this tool, no preconditions, and no mention of alternatives. An agent must infer usage purely from the resource it returns.

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 openWorldHint=false, so the safety profile is covered structurally. The description adds that only 'public' pages are fetched and that the result is converted to clean markdown, which is useful context, but it omits behavior for non-public or missing paths and any note on page size or truncation.

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 sentence with the operation and the output format front-loaded and no wasted clauses. The trailing 'for agent reading and summarisation' is mildly redundant since the audience is already implied, keeping it just short of a 5.

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 one fully described parameter, a covering annotation set, and no output schema needed to explain return values, the definition is nearly complete. It could still note what happens for invalid or non-public paths given openWorldHint=false, which is the only material 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 100% and the single 'path' parameter is fully documented with a default and examples in the schema itself. The description only reinforces the word 'public', adding no format, normalization, or query-string semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (Fetch), a specific resource (a public Tradehand website page), and the output format (clean markdown), which is enough for an agent to distinguish it from siblings like read_okf_concept or get_agent_discovery. However, it never explicitly contrasts itself with those siblings, so the differentiation is inferred rather than stated.

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 agent reading and summarisation' gives an implied context of use, but there is no explicit when-to-use versus an alternative, no prerequisites, and no statement of when this tool is the wrong choice over a sibling like read_okf_concept. Guidance is implied only.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description still adds useful behavior: the result is the catalogue's 'actual' services (not a synthesized or cached view) and the call has no side effects on inventory or bookability, and it can legitimately return nothing.

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, zero filler, and the primary purpose is front-loaded before the clarifying 'does not' clause. 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?

An output schema exists, so return-value explanation is not required, and the read-only nature is covered by annotations plus the explicit no-reservation statement. The only meaningful gap is that the lone required parameter is never described, which slightly underspecifies how to invoke it.

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?

There is one required parameter, publicReference, with 0% schema description coverage, so the description must carry the burden. It only indirectly implies the parameter identifies 'the listing' without naming it, explaining its format, or stating where it comes from, leaving the parameter largely 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?

The description gives a concrete verb+resource: it returns a listing's actual catalogue services, and it clarifies the scope by specifying 'when one exists.' It's clear enough to distinguish from a booking tool, though it never references the sibling tools because none of them are true alternatives.

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 implies the usage condition ('when one exists') and explicitly rules out the adjacent action by stating it does not reserve a slot or claim bookability, which steers the agent away from treating it as a booking call. It stops short of naming an alternative tool for the reserve/book case, so it isn't a full 5.

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 establish readOnly/openWorld/non-destructive, but the description adds real behavioral context beyond them: which fields are deliberately withheld (phone, street address, coordinates) and that instant quote data is still returned for listings with no purchasable catalogue. That is exactly the kind of edge-case disclosure annotations cannot 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?

Three short sentences, front-loaded with the action and identifier, with no filler. The instant-quote sentence is mildly tangential to selecting the tool but does carry useful behavioral information, so it 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?

An output schema exists so return structure need not be explained, and the description supplies the privacy scoping and the quote-availability edge case an agent would otherwise have to discover empirically. Only the lack of an explicit relationship to search_traders keeps it from being fully 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% for the single parameter, and its description already names 'search_traders' as the slug source, so the description repeats rather than extends the schema. No format, case, or validation detail is added, making the baseline 3 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?

States a specific verb+resource ('Return a public directory profile') and identifies the lookup key ('by listing slug'), which is enough to separate it from browse_trades or search_traders. It stops short of explicitly naming the sibling it complements, so it is clear but not sibling-differentiating.

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

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

There is no when-to-use statement, no stated prerequisite (e.g. 'requires a slug obtained from search_traders'), and no alternative named for cases where the caller only has a name rather than a slug. The only signal is the input key, which is already implied by the schema.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the output is raw markdown with YAML frontmatter left intact, which tells the agent what it will actually receive on a successful call.

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 core action stated first and the entry-point hint second. No filler, nothing repeated from the schema or annotations.

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 tool with annotations covering the safety profile and no output schema, the description supplies the necessary action, scope, return format, and entry point. Only minor gaps remain, such as what happens on an invalid or missing bundle path.

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% and the single path parameter is documented with concrete examples (/okf/costs/eicr.md, /okf/log.md). The description only reinforces the '/okf'-rooted domain and mentions the index file as a starting point, adding little 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: reads one file of the Tradehand Open Knowledge Format bundle under /okf, returning raw markdown with YAML frontmatter intact. The OKF-bundle scoping implicitly separates it from siblings like get_page_markdown, but 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?

Gives one concrete starting hint ('Start at /okf/index.md for the list of concepts'), which is implied guidance on how to begin. It never says when to choose this over get_page_markdown or any other sibling, and offers no exclusions or prerequisites.

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, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds real behavior beyond that: it enumerates what the result carries (claim state, source freshness, accreditation names, canonical profile URLs) and explicitly disclaims availability claims, mixed-source ratings, and any contact action — useful boundaries an agent could not infer from annotations alone.

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, and the core purpose is front-loaded before the return/boundary clauses. The second sentence is a dense run-on list, but every element (returns, disclaimers) carries information rather than restating the name.

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 an output schema present and annotations covering the safety profile, the description only needed to convey search semantics, result character, and boundaries — all of which it does. A small residual gap is the lack of explicit sibling routing, but nothing needed to call 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?

Schema description coverage is 75%, above the midpoint baseline, so the schema largely documents trade, location, and postcode itself. The description echoes the optional 'postcode or place' scoping but adds no syntax, format, or limit semantics beyond the schema (the undocumented 'limit' parameter is also untouched). Baseline 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?

States a specific verb and resource ('Find current public Tradehand directory listings') and the scoping facets (trade, optional UK postcode or place). It is clearly a directory search, but it never names or contrasts with the nearest siblings (browse_trades, get_trader), so the agent must infer the boundary 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 'by trade and optional UK postcode or place', and the negative clauses ('does not claim availability, expose mixed-source ratings, or contact anyone') set expectations about what the result means. However, there is no explicit when-to-use-this-vs-browse_trades-or-get_trader routing guidance, which is the main gap.

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