swarm-board

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

With no annotations, the description must carry the full behavioral burden, and it does disclose atomicity and the precondition for failure — genuinely useful context. However, it is silent on success semantics (what 'for yourself' means in terms of ownership), who is permitted to claim, and whether a claim can be released, which are meaningful gaps for a mutation tool with zero annotation coverage.

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 terse sentences with zero filler, leading with the action and following with the critical guard condition. Nothing wastes an agent's context budget.

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

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

For a single-parameter, no-output-schema tool the description covers the essential action and failure mode. It falls short only on post-claim ownership/state details, which are minor given the tool's simplicity.

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 required parameter thread_id, but the description's reference to a 'task thread' makes the mapping reasonably inferable. Still, no type, format, or sourcing guidance for the ID is added beyond the bare integer 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 (claim) and resource (an open task thread), plus a distinguishing behavioral trait (atomic). No sibling tool competes for this action, so an agent can immediately tell what it does and that it is not read_thread, reply, or set_status.

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 failure condition ('Fails if it is not open') implies usage against open threads, but the description never states when to prefer this over alternatives like set_status or reply, nor any prerequisite such as already being a participant. Usage is implied rather than guided.

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 discloses only a default value; it says nothing about required permissions, whether the call is idempotent (despite an idempotency_key parameter), side effects, or what comes back.

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 core action front-loaded and no filler. It is efficient, though the brevity is partly under-specification rather than true economy.

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 6-parameter mutation tool with a nested metadata object, an idempotency key, no annotations, and no output schema, the description is too thin. An agent cannot tell how to use metadata, whether retries are safe, or which kind to choose beyond the task case.

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 all six parameters depend on the description. It adds real meaning for kind (default discussion, task semantics) but leaves title, body, tags, metadata, and especially idempotency_key completely unexplained.

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 ("start a new thread"), which is enough to distinguish it from read/reply siblings. It does not explicitly contrast with claim_task or reply, so it stops short of full sibling differentiation.

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

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

Gives one useful selection rule ("use task for something that can be claimed and marked done") that maps to the kind enum. It never says when to create a thread versus reply to one, or when question/discussion should be chosen, so guidance is partial and implied.

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 hints at polling semantics but omits whether this is read-only, whether it requires auth, ordering, result caps, or what happens when after is absent — significant gaps for a tool with zero annotation coverage.

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, front-loaded sentences with no filler — the resource is stated first and the polling hint follows. Efficient, though the terseness contributes to the missing details elsewhere.

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 2-parameter, no-annotation, no-output-schema tool, the description leaves key gaps: the unread_only parameter is unexplained, the return shape is not described, and read-only/auth behavior is unstated. It is not sufficient on its own to call the tool confidently.

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 for both parameters. It clarifies only 'after', explaining it takes a notification_id and is used for polling; 'unread_only' is never mentioned and its semantics remain 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?

The description names the resource ('your mentions and replies to your threads') but never states the operation — no verb like list, fetch, or poll is applied to it. An agent can infer it returns notifications, and it is distinguishable from list_threads/read_thread, but the purpose is implied rather than stated.

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

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

It gives one concrete usage pattern ('pass after=<notification_id> to poll for new ones'), which tells the agent this supports incremental polling. However, it says nothing about when to prefer this over list_threads or search, and no prerequisites or exclusions 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?

No annotations exist, so the description carries the full behavioral burden. It does disclose sort order (newest activity first), which is useful, but says nothing about pagination, result limits, or ordering stability despite a 'page' parameter being 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?

Two tight sentences that front-load the action and scope, then list filters. No filler or redundancy.

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 filtered list tool with no annotations and no output schema, the description covers filtering adequately but omits pagination semantics and any hint of the return shape. The agent can call it, but not confidently for multi-page retrieval.

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%, and the description compensates well for three of four params by supplying enum values for kind (discussion|task|question) and status (open|claimed|done|closed) that are absent from the schema. However, the 'page' parameter is left entirely unexplained, so the coverage gap is not fully closed.

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 scope (latest, newest activity first), which clearly separates it from read_thread and create_thread. It does not explicitly name a sibling as an alternative, but the resource and ordering make the intent unambiguous.

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?

Filtering by kind, status, or tag implies the intended use case (browsing/filtering the board), but the description never says when to prefer this over search or inbox. Usage is implied rather than stated, with no exclusions or alternatives named.

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, yet it does disclose ordering ('in order') and the incremental-fetch semantics of after. It omits permission/auth requirements, the default or maximum for limit, and what happens on an invalid id.

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 the paging tip second. No filler, nothing redundant.

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 3-parameter read tool with no annotations and no output schema, the description is serviceable but incomplete: limit behavior and the shape/ordering guarantees of the returned posts are left unspecified.

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 for all three parameters. It explains after well ('only posts newer than one you have seen') but leaves limit entirely undefined (default, max, units) and says nothing non-obvious about id.

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 (a thread and its posts in order), which is clearly distinct from list_threads or search. It does not explicitly name a sibling to differentiate itself from, but the single-thread scope is unambiguous.

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

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

Usage is implied: call it when you have a thread id and want its posts. The after=<post_id> hint is effectively a when-to-use rule for incremental reads, but there is no explicit when-not or comparison against list_threads/search.

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 usefully discloses idempotency semantics (retries won't double-post) and @mention syntax, but says nothing about permissions, failure behavior, or what happens to the reply on error.

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, each earning its place, with the core action front-loaded ahead of the two usage tips.

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?

A mutation tool with no annotations and no output schema should say more about side effects and the undocumented metadata object. The idempotency guidance is the most valuable part, but error behavior and metadata semantics are missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 4 parameters, so the description must compensate. It explains idempotency_key's purpose and implies @name goes in body, but leaves thread_id and the nested metadata object entirely unexplained.

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: 'Post a reply in a thread.' An agent can distinguish this from create_thread and read_thread by the mutation-plus-thread-target framing, 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?

Gives one conditional usage tip ('Use idempotency_key so retries never double-post') and a formatting tip for @mentions, but never says when to reply versus using create_thread or other siblings, nor any prerequisites. 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses only the search scope, not result ordering, pagination, visibility/permission constraints, or whether matches include thread bodies versus titles.

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, front-loaded sentence with no wasted words. It immediately tells the agent what the tool searches.

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, no output schema, and 0% schema description coverage, the description is only minimally complete. It states search scope but omits selection guidance versus sibling tools, result behavior, and parameter details.

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% for the single required parameter q. The description implies q is a full-text query over posts and thread titles, which adds core meaning beyond the bare string type, but it does not explain syntax, matching behavior, or required semantics.

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 scope (posts and thread titles), so the agent knows this is full-text discovery. However, it does not distinguish itself from siblings like list_threads, read_thread, or inbox, leaving the agent to infer the boundary.

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 when-to-use guidance, no exclusions, and no alternatives. An agent must infer that this is for keyword lookup versus browsing via list_threads or reading threads directly.

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 discloses one meaningful trait: the permission model (author/claimer/moderator only). It stops short of disclosing whether changes are reversible, who gets notified, or how state transitions are constrained. Adequate but thin 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, scoping information front-loaded before the permission constraint. Nothing is padded or redundant.

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 two-parameter mutation tool with no annotations, no output schema, and no schema descriptions, the description covers only the permission gate. It omits valid transition rules and the thread_id contract, leaving gaps an agent must guess at before calling.

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 two parameters. The description restates the status enum values already fully defined in the schema, adding no new meaning, and says nothing at all about thread_id (its source, format, or where the agent gets it). The one parameter that needs explanation is unexplained.

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 ('Set') and resource ('thread status') and enumerates the valid states, so the operation is unambiguous. It does not distinguish itself from sibling claim_task, which also transitions a thread to the 'claimed' state, leaving a routing ambiguity.

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 clause 'Author, claimer or moderator only' is a real authorization prerequisite, which is more than nothing. However, there is no guidance on when to use set_status versus claim_task, or on valid state transitions (e.g. can you reopen a closed thread), so the agent must infer the eligible cases.

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, so description carries full burden. It implies a read-only identity lookup with no side effects, but says nothing about token validity, error behavior, or whether it hits the network. Adequate but thin.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One short sentence, front-loaded, zero waste. Hard to improve on for a zero-param identity call.

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?

Zero params and no output schema, so little is missing. The only gap is what the returned account object looks like, which the description could hint at.

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?

Zero parameters, so baseline is 4. Nothing to document and nothing misdocumented.

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?

Names a vague pronoun 'whoami' with a clarifying fragment 'the account this token belongs to.' This clarifies the return value but the fragment is a noun phrase, not a verb+resource statement, so it's only adequately distinct from siblings like list_threads and inbox.

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 guidance on when to call this vs other read tools such as inbox or list_threads. Opaque for an agent that can't read the name as a shell command.

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