ShellWire

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's contribution is the output contract: it preserves unknown facts, source evidence and checked dates, and produces no generated ratings. That is meaningful disclosure about what the caller gets back and what the tool deliberately does not fabricate. It does not discuss error behavior for invalid or duplicate IDs.

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, no filler. The core purpose and arity are front-loaded; the second sentence adds behavioral value rather than restating the name or title. 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 values need no explanation, and complexity is low (single parameter). Purpose, cardinality, distinctness and the no-generated-ratings contract are all covered. Missing only ID sourcing/format detail, which keeps it at 4.

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 carry some burden. It adds the 'distinct' constraint, which is not expressible in the schema, and restates the 1-4 cardinality. However, it never explains the required 'tool:<uuid>' ID format or where such IDs come from, leaving a real gap.

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 (compare) and resource (public tool IDs), plus the arity range (one to four distinct). The agent can distinguish this from fetch/search/get_chatbot_brief without opening the schema. It stops short of naming a sibling alternative for the common 'compare vs. fetch each' decision, so a 4 rather than 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?

There is no when-to-use or when-not-to-use guidance, and no mention of prerequisites (e.g. needing valid public tool IDs in hand) or when to prefer this over fetch/get_chatbot_brief. The second sentence describes output character, not usage context.

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 read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real value by disclosing the error/availability rule for unpublished and unknown IDs and by characterizing the payload as citable text and dated facts. No pagination or rate-limit detail, but nothing is contradicted.

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 with no filler; the core action and its scope come first, followed by the payload and the availability caveat. Every sentence carries information the agent can act on.

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 the description need not explain return values, and it still gives a useful preview of the content plus the failure mode. The only meaningful omission is format guidance for the id parameter, which matters for a tool that rejects malformed input.

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?

Only one parameter and schema description coverage is 0%, so the schema offers just a regex pattern with no prose. The description adds partial meaning by saying the id must be one returned by search, but it never explains the 'tool:'/'news:' prefix scheme encoded in the pattern or that IDs are UUIDs.

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 one public record') and scopes it to IDs produced by search, which separates it from siblings like search and list_my_submissions. It also previews the payload ('citable text and dated facts'). It stops short of naming the sibling tool explicitly or clarifying how it differs from the other get_* readers.

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 'returned by search' tells the agent this is a follow-up call after search, and 'Unpublished and unknown IDs are unavailable' defines a failure condition up front. There is no explicit 'when not to use' or a named alternative for discovering IDs, but the intended workflow is clear.

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, destructive=false and closed-world, so the safety profile is handled. The description adds real value beyond them: it discloses the payload shape (at most four labeled stories plus related public tools) and the empty-state behavior ('an empty brief remains empty'), which tells the agent not to expect a synthetic or error response.

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 no filler, and the primary purpose is front-loaded before the content-shape detail. The empty-brief clause is slightly idiomatically phrased but still earns its place by covering an edge case.

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 rich annotations, the description need not describe return formats or safety. It covers purpose, payload cap, and the empty state, which is adequate for a zero-required-parameter read tool; only the limit parameter's role is left unaddressed.

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 carry the meaning. It says 'at most four labeled stories', which loosely aligns with the limit parameter (default 4, max 4) but never names or explains the parameter, its 1-4 range, or what varying it does. Partial compensation, so a middling 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?

States a specific verb (Read) and resource (the source-reviewed chatbot brief), and anchors it to the same brief 'shown on the homepage'. No sibling tool overlaps with reading a brief, so differentiation is implicit rather than stated, keeping it just 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?

There is no explicit when-to-use guidance and no mention of alternatives among the siblings (compare_tools, search, fetch, etc.). The 'same as homepage' phrasing implies read-only retrieval context but never says when an agent should call this versus other read tools.

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=false, so the safety profile is covered. The description adds meaningful behavioral context beyond the annotations: the tool is anonymous, requires no credentials, explicitly offers no OAuth authentication, and discloses the kind of content it returns (OTP endpoints, bounded fields, binary uploads).

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 only three sentences and contains no obvious filler, so length is appropriate. However, the opening phrase 'Anonymous, credential-free instructions for authenticated private submissions' is internally tense and slightly confusing, and the final sentence partly repeats the credential-free idea.

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 tool with an output schema and strong annotations, the description covers the authentication model and content scope well. The main omission is usage routing against sibling tools, but the core behavioral and content information an agent needs is 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?

The tool has zero parameters, so the baseline is 4. The input schema is empty and fully covered; there is no parameter semantics for the description to clarify or contradict.

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 resource (builder submission instructions) and enumerates the content it returns: OTP HTTP endpoints, submission fields, screenshot uploads. It is distinguishable from the sibling submit_application, but it does not explicitly name or contrast with that or any other 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?

The description gives no explicit when-to-use guidance or alternatives. It notes that the tool itself is anonymous and credential-free, which implies a reading context, but it never says when an agent should choose this over submit_application or list_my_submissions.

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 cover the safety profile (read-only, idempotent, closed-world), and the description adds substantial context beyond them: an authentication requirement ('current verified builder token'), the scoping guarantee (only this account's records), explicit negative guarantees (never another builder's submission, operator notes, or contact email), and empty-result semantics ('Empty means no owned records').

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?

Four compact sentences, front-loaded with the auth prerequisite, and every sentence carries distinct information (auth, scope, empty-state, exclusions). Slightly dense but no filler.

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 need not be explained, yet the description still previews the payload (statuses, published tool URL, image previews) and covers auth and scoping. Nothing an agent needs to call this 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 tool takes zero parameters, so the baseline is 4; there is no parameter surface for the description to clarify, and none is needed.

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 ('Return ... this builder account's private submission statuses') and is anchored to the caller's own identity via 'my'. It does not name any sibling tool to differentiate against, but the purpose is unambiguous on its own.

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 way to check its own submission statuses, but the description never says when to use it versus siblings like get_submission_instructions or submit_application. The token prerequisite is stated, which gives some context, but no explicit when/when-not or alternative routing is present.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely behavioral detail beyond that: a hard result cap of 24 and the guarantee of stable IDs plus canonical citation URLs. It does not discuss ranking, relevance behavior, or what happens with zero matches, keeping it short of a 5.

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, no redundancy, with the scope of coverage stated before the return contract. Every clause carries 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?

An output schema exists, so spelling out returned fields is largely redundant, yet the 24-result cap is worth keeping. What is missing is the one thing the structured fields do not supply: how to phrase a query and when to choose this tool over its siblings.

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% for the single `query` parameter, so the description carries the full burden and adds nothing — no syntax, no expected format, no note about the 200-character limit. It only implies a search term exists.

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 enumerates the resources searched: public applications, chatbot catalog, and labeled news. Sibling tools (fetch, compare_tools, submit_application) are functionally distinct enough that no explicit differentiation is required, though none is offered.

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?

No when-to-use guidance, no mention of when to prefer this over fetch or compare_tools, and no prerequisites or query-context hints. The agent must infer that this is the entry point for discovery purely from the tool name.

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?

Adds substantial context beyond the annotations: auth requirements, the verified-backlink prerequisite, the non-publishing nature, and the dedup nuance that repeated pending normalized URLs are acknowledged without overwriting (refining the idempotentHint=false signal). The outcome_unknown recovery instruction is behavior 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?

Front-loads the prerequisites, then purpose, then caveats, then the recovery step, in five tight sentences with no filler. It is dense but appropriately sized for the complexity; minor cost is that constraints and purpose are interleaved rather than cleanly grouped.

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, return values need no explanation, and annotations cover the safety profile; the description fills the gaps that matter (auth, backlink, non-publishing, dedup, retry). The remaining hole is parameter-level detail for name/officialUrl/details, which neither schema nor description supplies.

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 carries the full burden. It adds real meaning for two parameters (email must match the verified account; images are uploaded separately via authenticated HTTP), but name, officialUrl, description, and the entire nested details object remain wholly 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 and resource ('Submit an app or personal agent') plus the decisive scope ('for private operator review... Does not publish'), which separates it from any publish flow. It also names the sibling to consult on an ambiguous outcome ('inspect list_my_submissions'), so an agent can route correctly without opening other schemas.

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 concrete preconditions (email OTP auth, verified root homepage backlink, email must match the account) and an explicit fallback path for outcome_unknown. It stops short of stating when NOT to use this tool versus siblings like verify_homepage_backlink or compare_tools, but the operational guidance is unusually clear.

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 supplying readOnly/openWorld/idempotent/destructive hints, the description still adds substantive behavior: authentication requirement, that the check is bounded and network-based, a five-minute cache window, no publication side effect, and rate limiting. These are exactly the operational traits an agent needs before calling a network-verification tool.

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?

Six short, telegraphic sentences with zero filler, front-loading the auth prerequisite and then layering constraints (scope, caching, no publication, rate limit). Every clause carries distinct 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?

An output schema exists, so return-value detail is unnecessary, and annotations cover the safety profile. Combined with auth, caching, rate-limit and no-publication disclosures, the definition gives an agent everything needed to invoke it 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 0% and officialUrl has no description in the schema, so the description carries the burden. It clarifies that the URL refers to the caller's public HTTPS site whose root homepage is inspected, which meaningfully disambiguates the single parameter, though it never states whether the input should be the bare origin or a full URL.

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 object ('Check a visible anchor to https://shellwire.com/ on the root homepage of your public HTTPS site'), including the exact target URL and the required location. No sibling tool (fetch, search, submit_application) overlaps with this narrow verification task, and the agent can distinguish it without opening the 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 the prerequisite (a verified builder Bearer token) and a key boundary ('No publication'), which implicitly separates it from submit_application. It does not explicitly state when in a workflow to run it or what to do on failure, so a 4 rather than a 5.

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