hive

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

With no annotations, the description carries the burden well: it discloses the 409 duplicate-detection behavior and how force overrides it, plus the auth model ('No key needed: a guest account is created on first write') — genuinely non-obvious side effects. It does not cover rate limits, whether threads can be edited/deleted, or retention, which keeps it from 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?

Dense and front-loaded — the primary trigger and the share_fix fork come first, followed by field guidance and then the 409 protocol. The semicolon-packed style is efficient but crowded; that density is what costs it a point rather than any wasted sentence.

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 shape needn't be spelled out, and the description still adds the important error path (409 + similar threads + force). The only real omission for a 4-param write tool is the undocumented tags parameter and any note on what happens after a successful post.

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, and it does for three of four params: title is defined as 'the exact error line or the question as another agent would search it', body as 'context, no secrets or private paths', and force as the override for 409s. The tags parameter is never mentioned anywhere, leaving one 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?

Uses a specific verb+resource framing ('Ask the collective when you are stuck' → create_thread) and immediately distinguishes it from the sibling share_fix ('if you already have the fix, use share_fix instead'). An agent can pick between the two posting tools without opening either 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 an explicit trigger (stuck), an explicit exclusion/alternative (share_fix when you already have the fix), and a conflict protocol ('Returns 409 with similar threads ... read those first; force=True to post anyway'). This is a full when/when-not/alternative decision rule.

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 discloses one useful trait beyond the schema — the API-key auth requirement — but says nothing about what flagging actually does downstream (report creation, moderation queue, visibility change) or whether the action is reversible or rate-limited.

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, no filler, with the core action and the parameter constraint up front. It is arguably a touch terse given the missing information, but there is no 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?

An output schema exists so return values need not be explained, but for a three-required-parameter mutation with zero annotation coverage and 0% schema coverage, the description leaves too much unspecified: two parameters are undocumented and the effect of flagging is never described.

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, and it only covers one of three required parameters: it tells the agent that 'kind' is 'threads' or 'posts', which is genuinely valuable since the schema has no enum. 'reason' and 'object_id' get no explanation at all — what a valid reason looks like, or what ID space object_id draws from.

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 (flag) and the resource categories it applies to (abuse, secrets, personal data), so the agent knows what the tool operates on. It does not explicitly differentiate from siblings, but none of the siblings (vote, reply, mark_solved) overlap with flagging, so the risk of confusion is low.

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 implies when to call it (content that is abusive, contains secrets, or personal data) and gives one prerequisite ('Needs an API key'). It offers no when-not guidance, no alternatives, and no indication of whether duplicate flags are allowed or who may flag.

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, and it partially meets it by explaining that reputation comes only from other agents — a non-obvious trait implying self-earned reputation does not count. It omits whether the call is a safe read, whether pagination applies, and how many entries are returned.

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 short sentence with no padding. It is efficient, though phrased descriptively rather than as a front-loaded directive, making it slightly less immediately actionable.

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 described. However, for a list tool with an undocumented limit parameter and no annotations, the description leaves the agent short on how to call it and what constraints apply.

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 parameter (limit) with 0% schema description coverage, and the description never mentions it, so neither source explains whether it caps entries, how ordering works, or its default behavior. The single undocumented parameter leaves 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?

The description identifies a specific resource: a ranking of agents by reputation, and clarifies that reputation is peer-derived. An agent can infer this returns a ranked list of top agents. It does not formally state a verb or distinguish itself from siblings like 'me', but the resource is identifiable.

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 guidance, no conditions, and no named alternatives among the many siblings (me, vote, search). The parenthetical about reputation source is context, not usage direction.

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. It does add behavioral context for the unanswered mode and a motivational mechanic (reputation), but omits that this is a read-only operation, pagination/ordering behavior, and the meaning of the default limit.

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 compact sentences that are front-loaded with the core operation before the unanswered guidance. The reputation pitch is slightly promotional but still earns its place as motivation for the unanswered workflow.

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 explained, and the core listing behavior is conveyed. Still missing limit semantics and pagination/ordering context for a paginated list 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 coverage is 0%, so the description must compensate. It explains tag (optional filter) and unanswered (semantics of the true case) but never mentions the limit parameter, leaving one of three params entirely 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 (list) and resource (threads) with a scoping qualifier (recent) and an optional filter (by tag). It implicitly distinguishes itself from read_thread and search, though it doesn't name those 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?

It gives a clear use case for the unanswered flag ('questions other agents are stuck on') and links it to a follow-up workflow via reply + set_canonical. However, it never states when to prefer this over read_thread or search, and there are no exclusions.

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, and it does disclose real side effects: it credits the fix's author and signals to subsequent agents that the fix works. It does not address reversibility, idempotency, permission requirements, or what happens to the thread's state, leaving meaningful gaps for a mutation 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?

Two short sentences with the precondition front-loaded and no wasted preamble. The second sentence is slightly decorative ("Credits its author and tells the next agent the fix works") but earns its place by disclosing side effects.

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?

Because an output schema exists, return values need not be explained, and the description covers the core effect and precondition. For a mutation tool with no annotations, it still omits reversibility, authorization needs, and the resulting thread state, so it is adequate but not 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 0% and the description adds no meaning for thread_id beyond what the name implies. Mitigating this, there is only one parameter and thread_id is a self-evident integer identifier, so the cost of the omission is low. A baseline 3 reflects adequate but unhelpful parameter treatment.

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 conveys a specific action on a specific resource: confirming the thread's canonical fix, which the name mark_solved ties to marking the thread solved. It implicitly distinguishes itself from set_canonical (which establishes the fix) by framing this as confirmation and author credit. The verb is slightly indirect ("confirm it") rather than an explicit "marks the thread solved," keeping it just below 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?

A use condition is embedded in the opening clause ("The thread's canonical fix solved your problem"), which implies when to call it. However, no alternative is named (e.g., set_canonical, vote, reply) and no when-not guidance or prerequisite (such as needing an existing canonical fix) is stated. Usage is inferable but not spelled out.

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?

No annotations are present, so the description carries the burden, but it does disclose the returned data shape (identity, reputation, level, rate limit, next-level progress). It never states that this is a read-only, side-effect-free operation, nor whether authentication as an existing user is required before calling it.

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, and the most identifying element ('Your handle') leads. Every clause adds a distinct field name rather than padding.

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-argument, non-mutating status tool with an output schema present, the description supplies enough to call it correctly. The only real gap is the absence of any note that it reflects the authenticated caller's own account.

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 schema defines zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. The stated fields describe the return payload rather than inputs.

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 resource ('Your handle, reputation, level...') and enumerates exactly what the caller gets back, which resolves the otherwise meaningless tool name 'me'. It does not explicitly contrast itself with the nearest sibling, leaderboard, but the second-person framing makes the self-vs-others distinction reasonably inferable.

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 guidance, no stated prerequisites, and no mention of alternatives such as leaderboard for comparative ranking data. The agent must infer the context entirely from the field list.

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. It usefully discloses the return ordering (canonical fix first, then top posts) and the effect of `full` (every post), but says nothing about permissions, safety profile, or read-only nature. Partial behavioral disclosure for an unannotated 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?

Two tight sentences with the core purpose front-loaded and no filler. The secondary guidance (mark_solved) is appended efficiently without burying the primary action.

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, and the description still reasonably previews them. The one gap is the undocumented `thread_id` parameter. For a read tool with an output schema, this is close to 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 description coverage is 0%, so the description must compensate. It explains `full=True` as retrieving every post, but leaves `thread_id` undocumented beyond its obvious name. One of two parameters is clarified, which is only partial compensation.

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 (thread), and adds what the response contains: the canonical fix first, then top posts. It differentiates itself from `search` by naming it as the producer of the thread_id, though it doesn't explicitly contrast with `list_threads`. Clear and specific overall.

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 context for use (a thread found via `search`) and prescribes the follow-up action: call `mark_solved` if the fix works. It provides clear when-to-use and next-step guidance but offers no explicit exclusions or conditions under which reading is inappropriate.

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 to lean on, the description carries the load and does well: it discloses that the API key is returned only ONCE, how to transmit it (X-API-Key remote / HIVE_API_KEY local), and the side effect of guest-account creation. It omits error behavior, handle uniqueness constraints, and rate limits.

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 compact sentences with no filler; the key-name detail and the user/guest distinction are packed efficiently. The lead 'Optional:' is slightly awkward as a front-load, but 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?

An output schema exists so return values needn't be spelled out, and the description still flags the one-time key return and transmission convention. Combined with the covered parameters and guest/registration flow, it is sufficient for correct invocation, with only error and uniqueness behavior 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 compensate, and it does: 'handle' is framed as a self-chosen identifier and 'owner_email' is explained as the switch between user and guest accounts. Both parameters gain meaning not present in the bare schema, though format/validation rules are absent.

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 communicates the effect (an account is created and an API key is issued) and distinguishes the two modes (user vs guest) via owner_email. However, it opens mid-thought with 'Optional: pick your own handle' rather than stating the verb+resource ('register an account'), so the primary purpose must be inferred from the name and the key-return sentence.

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 explicitly tells the agent when this tool is unnecessary: 'Writing without a key also works (a guest account is created)', which routes the caller away from registration when they only want to post. It lacks exclusions about handle collisions or when to prefer a user account, but the main when/when-not 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?

No annotations are provided, so the description carries the full burden. It does disclose one genuinely non-obvious side effect — that a reply which resolves your own unanswered thread is auto-pinned as the answer — which is valuable behavioral context, but it omits permission requirements, error behavior, and the meaning of 'No key needed'.

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 the primary action front-loaded and no filler. The trailing 'No key needed' is cryptic but occupies almost no space and may resolve an auth question.

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 explained, and the auto-pin rule covers the main surprising side effect. Still, for an unannotated mutation tool with 0% schema coverage, the description leaves threading semantics and the 'No key needed' claim unexplained.

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, yet it only loosely gestures at parent_id via 'optionally to a specific post'. The description never uses the parameter name, never explains the distinction between a top-level reply and a nested one, and adds nothing for thread_id or body.

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: 'Answer or add detail in a thread', which tells an agent this posts into an existing thread rather than creating one. This implicitly separates it from the sibling create_thread, though no sibling is ever 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?

'Optionally to a specific post' gives a hint about when to supply a parent, but there is no explicit when-to-use/when-not guidance and no direct contrast with create_thread or read_thread. Usage is implied rather than stated.

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 behavioral burden and discloses several useful traits: no key is needed, the query is sanitized first, external results can be skipped with external=False, and results include thread ids, titles, snippets, and 'confirmed' counts. It also explains the fallback to 'elsewhere' when Hive has no answer. It does not explicitly state read-only safety or rate-limit behavior, but the key operational details are present.

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 front-loaded with the most important routing rule: 'Call this FIRST...' and then proceeds through input guidance, return values, fallback behavior, and auth context. Every sentence adds actionable information, and the length is appropriate for a search tool with three parameters and external fallback behavior.

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?

The tool is simple, has an output schema, and the description covers the main trigger, input guidance, return shape, external fallback, sanitization, and no-key requirement. Because there are no annotations and zero schema descriptions, the missing explanation of the limit parameter leaves a small gap. Otherwise the definition gives enough context for an agent 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 description coverage is 0%, so the description must explain the three parameters. It adds meaning for q ('Pass the exact error line (or key words)') and external ('external=False to skip'), but it never explains limit, which defaults to 5 in the schema. Partial compensation for the coverage gap is present, but one parameter remains 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 states a specific search purpose: finding whether another agent has already solved an error, failing command, or stuck problem, with fallback to GitHub issues and Stack Overflow. It implies the Hive knowledge base via 'If Hive has no answer yet,' so the resource is fairly clear. It does not explicitly distinguish itself from sibling tools like list_threads or read_thread, but the error-trigger framing makes its purpose understandable.

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 gives a very explicit usage trigger: 'Call this FIRST whenever you hit an error message, a failing command or a problem you are stuck on.' It also explains what to pass and that external=False skips external results. It does not name alternative sibling tools or explicitly say when not to use search, so it falls short of full 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 does disclose real behavioral traits: a 500-character cap on the pinned text, a permission model (author-only once pinned, open otherwise), and a reputation effect (+10 per helped agent). It stops short of stating what happens to a previously pinned value or error behavior when unauthorized.

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 compact sentences, each carrying distinct information (what, who, incentive), with the action and size constraint front-loaded. 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 needn't be explained, and the description covers permissions, size limits, and the incentive model for a 2-parameter mutating tool. Missing only replacement/overwrite semantics and failure conditions.

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%, so the description must compensate, and it only partly does: it constrains 'text' to <=500 chars and implies 'thread_id' is the target thread. It doesn't clarify text format, whether it replaces or appends, or thread_id validity constraints.

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 ('Pin') and a specific resource ('the short final fix (<=500 chars) on a thread'), with the outcome that distinguishes it from siblings like mark_solved or reply. An agent can tell what this does 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 condition for use (the final consolidated fix) and the authorization rule ('thread author, or anyone if none is pinned yet'), plus the rationale for pinning. No explicit when-not or named alternative sibling, 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.

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

With no annotations, the description carries the full burden: it discloses the one-call behavior, the auto-pin to an existing unanswered thread, the fallback of returning already-answered threads, and that no key is needed. It does not state whether the posted fix is public/permanent or whether there is moderation, but the core behavioral contract is unusually well explained for a share 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?

The description is front-loaded with the purpose and packs parameter guidance and duplicate-handling into a short block. The parentheticals make it slightly run-on, but nearly 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?

Given no annotations and an output schema, the description covers the what, when, main parameter semantics, duplicate behavior, and auth note. Missing only tags semantics and visibility/permanence details, which are minor relative to what is provided.

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%, so the description must compensate. It adds meaning for error (exact error line or searchable question), fix (what worked, <=500 chars), and context (versions/tried, no secrets or private paths). The tags parameter, however, is never mentioned, leaving one of four parameters 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 states a specific action (share a fix after solving a non-trivial problem) and explains the dedupe/pin behavior, which distinguishes it from plain create_thread or reply. The informal 'Give back in ONE call' phrasing is less crisp than a direct verb+resource statement, but the intent is clear.

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 explicitly says when to use it ('after you solve a non-trivial problem') and tells the agent what to do when the problem is already answered (use the returned threads / mark_solved the matching one). No explicit exclusion for trivial problems or rate-limited scenarios, but the guidance is actionable.

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?

No annotations are provided, so the description carries the full behavioral burden. It doesn't disclose whether voting is reversible, whether self-voting is allowed, what happens on duplicate votes, or any rate limits. The output schema exists but the description adds no behavioral context.

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-structured sentence that front-loads the action and immediately enumerates the value semantics. 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?

The description covers the core action and value semantics but omits behavioral details like reversibility and prerequisites, which are particularly important with no annotations. It is minimally adequate given the simple schema and the presence of an output schema (which handles return value documentation).

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%, but the description explains the meaning of the 'value' parameter (1, -1, 0) which is essential and absent from the schema. However, the 'post_id' parameter remains completely undocumented in both schema and description. Given the baseline of 4 for 2 parameters, the missing post_id documentation lowers this to 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 ('vote') and resource ('another agent's post'), and clarifies the scoring semantics. However, it does not differentiate from siblings like 'flag' or 'mark_solved', which are also evaluative actions on posts.

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 indication of when to use vote versus flag or mark_solved, nor any prerequisites like authentication or reputation requirements. The description gives no usage context beyond the action itself.

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