Shiplist

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral detail — 'live' implies non-live/unpublished listings are not returned — but says nothing about error behavior for a missing or unpublished slug.

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 verb and resource, with zero filler. Nothing needs trimming and nothing important is buried.

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 one-parameter read tool with annotations covering safety and a fully documented schema, the description is nearly sufficient. The only gap is the not-found / not-live case, which for a 'live listing' lookup an agent might reasonably want spelled out.

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% with the single slug parameter fully described and even sourced ('e.g. from search_listings'). The description adds no format or syntax detail beyond the schema, so the baseline 3 for a fully documented schema 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?

The description names a specific verb (get) and resource (one live listing) with a clear retrieval scope, so an agent immediately understands this is a single-item fetch rather than a search. It does not explicitly contrast itself with sibling search_listings, though 'one ... by its slug' implicitly separates it.

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: 'by its slug' tells the agent a slug is required, and the schema note 'e.g. from search_listings' hints at the workflow, but that guidance lives in the schema, not the description. There is no statement of when to use this versus search_listings or what happens if the listing is not live.

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 and openWorldHint=false, so safety is covered. The description adds genuine behavioral context by disclosing the possible returned states and that a verification verdict with reasons accompanies them — useful, though it says nothing about polling cadence or how long 'review' states persist.

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 that packs the outcome states and the additional verdict payload without a wasted word. Nothing is buried or repeated.

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 convey what comes back, and it largely does: status values plus verification verdict and reasons. It is slightly thin on whether the verdict is always present and on the 'review' lifecycle, but it is adequate for a one-parameter read 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?

There is a single required parameter with 100% schema description coverage, so the schema already documents it fully ('Submission id returned by submit_listing'). The description adds no syntax, format, or sourcing detail beyond that. 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 (check) and resource (a submission) and enumerates the outcome space (pending, review, live, rejected) plus the verification verdict/reasons. The purpose is unambiguous, though it never names a sibling to differentiate itself from the other listing/submission tools.

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

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

Usage is only implied: an agent can infer this is called after submit_listing to poll the outcome, and the schema note 'id returned by submit_listing' reinforces that. There is no explicit when-to-use, when-not, or alternative-tool 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered structurally. The description adds only that the returned ids are 'valid' for submit_listing, implying the list is the accepted-value set, but says nothing about ordering, completeness, or caching of the 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?

A single sentence with no waste, front-loading the resource and immediately tying it to its purpose. Nothing could be trimmed without losing the submit_listing link.

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 parameters, no output schema, and annotations covering the safety profile, the description is nearly complete; naming 'ids and names' effectively substitutes for the missing output schema. Only a note on ordering/stability of the list is absent.

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 100% and no enum or nested-object semantics are at issue.

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 valid category ids and names') and scopes the result by naming its consumer, submit_listing. It is clearly distinguishable from siblings like get_listing or search_listings, though it does not explicitly say it is the only category-lookup tool.

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 submit_listing' implies the tool exists to supply valid category ids before a submission, which is useful implied usage. However, it never states the trigger explicitly (e.g., 'call this before submit_listing') nor rules out any alternative or condition.

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 and openWorldHint=false, so safety is covered. The description adds the scoping detail that search covers 'live' listings and which fields are matched, which is useful context. It does not describe pagination or result ordering beyond 'newest' when query is omitted.

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, front-loaded with the core purpose and followed by the key usage modifier. No wasted words.

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

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

Complete enough for a read-only search tool with full schema coverage and annotations covering the safety profile. The main minor gap is that no sibling alternative is named, but the core invocation requirements are all 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 all three parameters are already documented in the schema. The description reinforces the optionality of query and the default browse behavior, but adds little syntax or format detail beyond what the schema provides.

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 (live Shiplist listings), and clarifies the search surface (name, tagline, description, tags). It is not explicitly distinguished from siblings like get_listing, though the list/search dichotomy is reasonably implied.

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 one concrete usage condition: omit query to browse the newest. It does not mention alternatives (e.g., get_listing for a single listing) or when not to use it, so guidance is implied rather than explicit.

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 annotations already covering the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description still adds real behavioral value: the returned submission id, the pending state gated on an emailed confirm link, the 48-hour expiry, and the follow-up tool to poll. It does not explain what happens on duplicate submissions despite idempotentHint=false, nor any auth/rate-limit constraints.

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 front-loaded sentences with no filler; the purpose leads and the operational caveats follow. The final sentence is dense and packs return value, state machine, expiry, and next tool into one line, which is efficient if slightly crowded.

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?

No output schema exists, yet the description discloses the return value (submission id) and the full async lifecycle including expiry and the polling tool. Combined with 100% schema coverage for input, an agent has everything needed to submit correctly and handle the result.

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 all 8 parameters including lengths, formats, and the makerEmail confirm-link behavior. The description adds no field-level syntax or format detail beyond that, so the 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?

Opens with a specific verb+resource ('Submit a product to Shiplist') and adds a scope qualifier ('on the maker's behalf'). This is clearly separable from the read-only siblings get_listing, search_listings, list_categories, and get_submission_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 explicit preconditions for calling it ('Only submit what you verified from the product's repo or site, and only with the maker's go-ahead') and routes the agent to get_submission_status for polling. It stops short of stating when NOT to use it or which sibling to prefer for listing lookups, but the context is clear.

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