privatedock

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description still adds genuine context the annotations do not: only 'published' listings are returned, which tells the agent that unpublished slugs will not resolve.

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 qualifier 'published' is placed before the retrieval target where it matters. It is terse to the point of omitting return-shape information, which keeps it from 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?

For a simple single-entity read with complete schema and rich annotations, the description is nearly sufficient. However, with no output schema, nothing is said about what a returned contractor record contains or what happens when the slug is unpublished or unknown.

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 'slug' parameter is fully documented with pattern and length constraints, so the schema carries the load. The description's 'by its slug' adds nothing beyond that 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 states a specific verb and resource ('Get one ... marine contractor') and narrows the scope to 'published' entities keyed by slug. It implicitly distinguishes itself from the list_*/search_listings siblings by being a single-entity lookup, though it never names them.

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: an agent can infer this is the tool for fetching a known slug, as opposed to search_listings. There is no explicit statement of when to use it versus search_listings, nor any prerequisite or not-found handling 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 declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds the useful behavioral fact that it returns aggregate counts restricted to 'published' entities and a last-changed timestamp — meaningful context an agent would not get 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?

A single well-formed sentence with zero filler; the count outputs and the freshness timestamp are front-loaded and nothing is 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 zero-parameter, annotated read tool this is essentially complete: the agent knows what is counted, that only published items count, and that a last-updated value is returned. With no output schema, a slightly clearer statement of the return shape would have been the only improvement.

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, which is the baseline-4 case. The description correctly implies a no-argument, global summary with no filtering scope to specify.

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 ('Get the number of') and three concrete resources (marine contractors, places, categories) plus a freshness metric ('when the data last changed'). The emphasis on counts implicitly separates it from list_categories and list_places, which return entries rather than totals, 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: an agent can infer this is the summary/count tool rather than the enumeration tools, but the description never states when to prefer it over get_listing or the list_* siblings. No exclusions or prerequisites are given.

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, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered. The description adds that counts are aggregated per category, which is useful return-shape context, but says nothing about ordering, pagination, or whether empty categories appear.

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 ten-word sentence with zero filler that front-loads the action and resource. 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?

For a parameterless, closed-world list tool with annotations covering safety and idempotency, the description conveys enough: what is listed and that counts accompany each entry. The only gap is result volume/ordering, which is minor at this complexity level.

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; there is nothing for the description to disambiguate. Schema coverage is nominally 100% because the object is empty.

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 categories") plus the payload shape ("with their marine contractor counts"), so an agent knows exactly what comes back. It does not distinguish itself from siblings like list_places or list_sources beyond the noun, leaving the agent to infer the domain split.

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 are no explicit conditions for when to call this versus get_stats or search_listings, and no prerequisites or exclusions named. Usage is implied by the name and description only — an agent can guess it is the enumeration call for categories, but nothing confirms it.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description does add one genuinely useful behavioral fact — the result set is restricted to places with marine contractors, not all geography — but says nothing about ordering, pagination, or the shape of each entry.

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 short sentence, front-loaded with the verb and resource, with the scoping qualifier at the end. Every clause earns its place and there is nothing to trim.

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 is the only place to learn what a returned 'place' looks like (name vs. ID, hierarchy, grouping). It establishes the domain but not the return shape or how the values should be fed into sibling filters, leaving a real gap for a discovery 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The sentence correctly implies the call needs no input, matching the empty 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 ('List') and a specific resource ('countries, regions and cities'), plus a meaningful scope qualifier ('that have marine contractors'). It separates itself from search_listings and get_listing by resource type, though the distinction from list_categories/list_sources is only implicit in the noun.

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 or when-not-to-use guidance and no sibling is named. The agent must infer that this is a facet/discovery tool used to obtain valid place values before calling search_listings; that inference is left entirely to the reader.

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, closed-world behavior, so the description is free to add value — and it does by declaring what each record contains (license and refresh metadata). It stops short of saying whether the list is paginated, ordered, or complete, but with annotations covering the safety profile this is solid.

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 no waste; the resource is front-loaded and the returned field hints come second. Nothing to trim.

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 so at a useful summary level (license and refresh per source). For a simple parameterless list tool that is nearly enough; minor gaps are ordering and completeness guarantees.

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; there is no parameter semantics to explain and the description need not compensate for anything.

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 (List) and resource (marine contractor data sources) plus the payload (license and refresh per source). It is clearly distinct from siblings like list_categories or get_stats by virtue of the resource, but never names an alternative to reinforce the distinction.

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: an agent can infer this is for provenance/licensing questions. There is no explicit 'use this when...' framing and no exclusion of alternatives, though the parameterless nature makes the surface small.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile needs no repeating. The description adds the 'published' visibility constraint, which is useful, but says nothing about result shape, pagination behaviour or empty-query semantics that would go beyond the structured fields.

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 the qualifying scope constraint come first. Nothing redundant is included.

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?

Eight optional parameters and no output schema mean the description should say more about what a default call returns and how paging works. It is adequate only because the input schema carries unusually rich per-parameter documentation, leaving the description itself thin for a multi-facet search 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 100%, and the schema itself documents typo fallback, slug sourcing, sort defaults and cursor reuse far better than the description does. The description only echoes the facets (text, place, category) already enumerated per-parameter, so baseline 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 (Search) and resource (published marine contractors), plus the three axes of matching (text, place, category). It is clearly a collection-level search versus the singular get_listing sibling, though it never names siblings 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?

The word 'published' implies a scope restriction, and the queryable facets are listed, but there is no explicit when-to-use/when-not guidance, no statement that omitting q returns an unfiltered listing, and no pointer to get_listing for single-record retrieval. Usage is only implied.

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