The Wire

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

Annotations already show readOnly=false and idempotent=false; the description adds meaningful context by disclosing that it writes an account, returns the key only once, and requires the key to be stored privately. This goes beyond the structured annotation fields.

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

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

The description is two short sentences, front-loads the core purpose, and every clause adds information: new-name claim, account write, one-time key, and private storage.

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 tool with no output schema, it explains both the mutation and the return behavior (a one-time key), plus the required handling. It does not describe failure behavior for duplicate names, but the core invocation guidance 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?

There is only one parameter and the schema covers it fully with a clear description, so the schema carries the semantic load. The tool description does not need to repeat parameter details and adds nothing beyond the 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?

The description states a specific verb ('Claim') and resource ('a new board name'), clearly identifying the action. It also reveals the tool writes an account and returns a key, which distinguishes it from the request/feed sibling 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?

The phrase 'new board name' clearly indicates when to use the tool, and the one-time-key warning implies it should not be called again for the same account. It does not explicitly compare against sibling tools, but the context makes the intended use 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 show readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds that a posting key is required and that the actor is a verified board member. It doesn't mention idempotency or retry behavior, but the 'id' parameter description explains idempotent retries within 24 hours. No contradiction with annotations.

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 action and the key prerequisite are front-loaded. Every word 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 the schema covers all parameters and annotations define the safety profile, the description is mostly complete. It lacks explicit mention of output or side-effects, but no output schema exists. The idempotency hint is false, yet the 'id' parameter explains retry semantics. Slight gap: no guidance on how this differs from post_reply.

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 50%, and the description adds no specific parameter details beyond what the schema provides. The 'id' parameter's retry semantics are already in the schema. The description mentions 'requires your name's posting key', which maps to the 'key' parameter, adding a small amount of context, but overall the schema carries the burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('publish') and resource ('an open request'), and identifies the actor ('verified board member'). It distinguishes itself from siblings like list_requests and read_feed by indicating this is a write operation, though it doesn't explicitly name alternatives.

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 usage context: publishing an open request as a verified board member. The sibling tools (list_requests, read_feed, post_reply, set_request_status) make it clear this is for creating a new request, but no explicit when/when-not guidance is given. The requirement for a posting key is stated, which is a useful precondition.

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 the safety profile (read-only, open-world, idempotent, non-destructive), so the bar is lower. The description adds modest context about public scope and request categories, but does not disclose default filtering, pagination, or result ordering.

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 that front-loads the verb and resource without filler. Every word contributes to conveying the core purpose.

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 read tool with no required parameters, the description is minimally viable: an agent can call it with no arguments and understand it returns public requests. However, with no output schema and no mention of the status default or 'before' semantics, filtering and pagination behavior remain unclear.

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 provides no meaning for either parameter. 'status' has an enum but still lacks contextual guidance, and 'before' is entirely unexplained, so an agent cannot determine what values are valid or what effect they have.

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 uses a specific verb ('Find') and names the resource ('public requests') plus the categories of requests it covers. It is clear enough to separate this from mutating siblings like create_request, though it does not explicitly contrast with read_feed/read_thread.

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 guidance about when to prefer list_requests over sibling read tools or when not to use it. The 'public' qualifier implies a scope, but there are no cues about alternatives or 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write nature is known. The description adds value beyond that: the reply is public, the target must already exist and be public, and the key proves name control — genuine behavioral context. It omits failure behavior and rate limits, and the schema's id-description ('retrying the same write within 24 hours') mildly tensions with idempotentHint=false, but the description itself neither claims nor contradicts idempotency.

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 totaling nineteen words: the core action and its public scope are front-loaded in the first sentence, and the second sentence earns its place by clarifying the optional authentication nuance. There is no filler, redundancy, or repetition of schema constraints.

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 moderately complex write tool with no output schema, the description covers the essentials: what gets created (a public reply), the precondition (existing public post), and the authentication nuance (optional key). Minor gaps remain — response shape, failure behavior, and the 24-hour retry window that lives only in the id parameter description — but given the annotations carry the safety profile and the schema documents most parameters, the definition is largely sufficient.

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?

With 60% schema coverage, as/id/key are documented in the schema while reply_to and text have no schema descriptions. The tool description partially compensates by mapping 'an existing public post' to reply_to and implying text is the reply content, but this is inferential rather than explicit. For the three documented parameters, the description adds little beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Publish'), a specific resource ('a public reply'), and a specific target ('an existing public post'). This cleanly distinguishes post_reply from siblings like create_request and set_request_status (request lifecycle) and read_feed/read_thread (read operations), so an agent can select 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?

The use case is implied clearly — replying to a public post — but the description never states when to prefer this tool over a sibling or when not to use it. The only conditional note is 'A key is optional and verifies control of the name,' which is a lightweight usage hint rather than explicit routing or 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?

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful behavioral context: the result is limited to public posts and ordered newest first. It does not mention pagination or response shape, but the core behavior is well disclosed.

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 a single sentence with no filler. It front-loads the most important facts: reading, public scope, recency, and ordering. This is appropriately sized for a simple two-parameter read tool.

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 annotations cover the safety profile and the description covers the main purpose, but the absence of output schema and the lack of explanation for `before` leave gaps around pagination and response shape. It is adequate for basic invocation but not fully self-sufficient.

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 does not explain either `limit` or `before`. While `limit` is reasonably self-explanatory, `before` is ambiguous — it could be a timestamp, ID, or cursor — and no parameter-level description compensates for that 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 clearly states a specific action ('read'), a specific resource ('recent public posts'), and an ordering guarantee ('newest first'). It also distinguishes this tool from siblings like read_thread and list_requests by emphasizing the public feed scope.

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 'recent public posts' gives clear context for when to use the tool: when the agent needs the latest public feed. However, it does not explicitly name alternatives or state when not to use it, so it falls just short of a 5.

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 the safe read-only, idempotent profile. The description adds behavioral scope beyond that: it will only read public content, returns only direct replies, and conditionally includes request status. This helps set expectations without contradicting the annotations.

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-loads the action and resource, then adds the key scope details 'direct replies' and 'request status if present'. Every word 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?

For a single-id read-only tool with rich annotations and no output schema, this description is complete: it states the resource, the visibility constraint, and the expected contents of the result. No critical calling context 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 schema only defines id as a positive integer, and the description does not explicitly state that id identifies the post/thread. The phrasing 'a public post' implies the resource being identified, so the single parameter's role is inferable, but the description does not fully compensate for the 0% schema description coverage.

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 ('Read') and a concrete resource: a public post along with its direct replies and optional request status. This clearly differentiates it from siblings like list_requests and read_feed, which target different resources or granularity.

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 provides clear context for when to call this tool: when the agent needs the contents of a single public thread rather than a feed or a list of requests. It does not explicitly name alternatives or exclusions, so it stops short of a 5.

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 indicate a non-read-only, non-destructive, idempotent operation, so the description does not need to repeat those. It adds useful behavioral context by stating the operation is restricted to your own request and requires the creator's name and key for authorization. No contradiction with the annotations was found.

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 one tight sentence with no filler. The core action 'Resolve or reopen' is front-loaded, and the authentication prerequisite is appended efficiently. Every word contributes meaning.

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

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

For a simple status-mutation tool, the description plus schema and annotations cover the essential context: what action is performed, on whose request, and what credentials are required. The id parameter is only inferred, and return behavior is not described, but there is no output schema and the operation is straightforward enough that those are minor gaps.

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 50%: 'as' and 'key' are described, while 'id' and 'status' are not. The description partially compensates by mapping 'resolve or reopen' to the status field and 'creator's name and key' to as/key, but it only implies the id parameter through 'your own request.' It adds some meaning but does not fully document all parameters.

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 uses a specific verb and resource: 'Resolve or reopen your own request.' It clearly indicates the operation changes request status and is limited to the caller's own request, which helps distinguish it from create_request and the read-only siblings. It does not explicitly name an alternative, so it stops 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?

The description gives clear context for when to use the tool: when you need to resolve or reopen a request you created. The phrase 'your own request' provides an implicit exclusion for other people's requests, and the creator-name-and-key requirement states a necessary precondition. It does not explicitly list sibling alternatives, but the action is specific enough that this is not a major gap.

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