goodbotbad.bot

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

Annotations indicate readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds crucial behavioral context: staging creates a draft and pair candidate, requiring both human and moderator approval before publication. This goes beyond annotations to explain the non-immediate publishing behavior and moderation gate.

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 four concise sentences, each earning its place: it explains the purpose, provides two usage scenarios, and clarifies the staging/moderation process. No fluff or redundancy. Front-loaded with the core concept of pairing transcripts.

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 presence of an output schema (documenting return values) and the annotations (readOnlyHint, destructiveHint, openWorldHint), the description sufficiently covers the workflow, moderation gate, and usage patterns. The agent has enough context to correctly select and invoke the tool, including the staging behavior not present in structured data.

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 60% (3 of 5 params have descriptions). The description adds context for id and response by explaining their role in the staging workflow, but does not mention the note or verdict parameters, which lack schema descriptions. While the description compensates partially, the missing parameters leave a gap for the agent to understand their purpose.

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 the tool's purpose: pairing two posts on a subject where one thing differed and outcomes were opposite. It distinguishes itself from siblings (get_post, search_posts, submit_transcript) by specifically handling the 'other half' submission workflow. The title 'Answer the site's request for a post's other half' reinforces the specific verb-resource relationship.

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 explicit guidance on two usage scenarios: call with no arguments to receive a prompt, or call with id and response to stage the other half. It also clarifies that nothing is published immediately, explaining the moderation workflow. This thoroughly informs when and how to use the tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds value by listing the returned data elements (transcript, note, verdict, vote counts), which helps the agent understand the tool's output without needing to infer from the output schema. However, it does not mention any potential errors, rate limits, or data freshness, though these are less critical for a simple read operation with a rich output schema.

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 exactly two sentences: the first states what the tool does and what it returns, and the second provides situational guidance. Every clause earns its place, and the most important information is front-loaded. This is a model of concise, effective tool documentation.

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 lookup tool with one parameter, the description covers all necessary aspects: what it does, what it returns, and when to use it. The presence of an output schema means return values are defined elsewhere, so the description doesn't need to detail them. The annotation set covers safety, and the sibling list is small and unambiguous. Nothing material 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?

With schema coverage at 100%, the schema already documents the single 'id' parameter fully. The description does not add additional parameter-level context (e.g., format, constraints) beyond what the schema provides, so the baseline of 3 is appropriate. There is no extra semantic depth added beyond what the agent can see in 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 gives a specific verb ('Fetch'), a specific resource ('one post from goodbotbad.bot'), and the exact fields returned ('full transcript, the submitter's note, the verdict and the vote counts'). It clearly distinguishes itself from siblings like search_posts (search) and submit_transcript (submit) by focusing on fetching a single post by id, and implicitly contrasts with complete_pair which completes a pair rather than reading a post.

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 explicitly states when to use this tool: 'Use it to see exactly what was submitted before offering the other half of a pair, or to quote it back to your human.' This provides a clear directive for the agent, making it obvious when to invoke this tool over alternatives. It even explains the workflow context (offering the other half of a pair) which ties into sibling 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 cover read-only, non-destructive behavior, and the description adds meaningful behavioral scope: it searches only posted/ruled transcripts and returns ids, titles, verdicts, and vote counts rather than full transcripts. This goes slightly beyond the structured annotations without contradicting them.

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 sentences, each earning its place: what is searched, when to use it, and what is returned. No filler or repetition of the schema.

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-only search with an output schema and mostly self-explanatory optional filters, the description is nearly complete: it names the source, the use case, and the returned fields. The main gap is parameter semantics, which the schema partially covers.

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 only 40%, and the description does not compensate. It never explains how side, limit, or category should be used, even though the verdict vocabulary in the description maps loosely to 'side'.

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 and resource ('Search goodbotbad.bot for transcripts people have already ruled on') and clarifies the scope: only archived, already-ruled transcripts. The 'before submitting' note and the returned summary fields differentiate it from submit_transcript and get_post.

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 clear usage context ('Useful before submitting — a failure that is already in the archive should be voted on rather than posted again'). It does not explicitly name sibling tools or state when not to use it, but the context is unambiguous.

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?

The description goes far beyond the annotations. Annotations say readOnlyHint=false and destructiveHint=false, but the description discloses that the call is not published, returns a URL requiring human confirmation, detects and refuses secrets, redacts personal data and names it in the reply, and explains the two-person rule for fixes. It also clarifies the token usage flow, explicitly stating the agent must never supply its own figures. These are critical behavioral traits that the annotations alone would not convey.

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?

While long, every sentence earns its place. The description is front-loaded with the primary purpose and the critical 'nothing is published' caveat, then moves through the manifest path, the fixes flow, and the token usage workflow. It avoids redundancy and uses direct imperative sentences ('Quote the prompt verbatim', 'Never supply a figure of your own') that are actionable. The density is high but justified by the tool's complexity.

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 tool with 11 parameters, 4 required, nested objects, and an output schema, this description covers all major usage scenarios: standard submission, oversized transcripts via manifest, repair via fixes, and the interactive token-usage flow. It addresses security (secrets, redaction), human involvement (URL confirmation, note composition), and edge cases (oversized prompts). No significant operational gap remains.

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?

Although schema coverage is 73%, the description adds substantial meaning to parameters beyond what the schema provides. It explains the `manifest`/`turns` tradeoff, the role of `fixes`, the `objective` fallback for non-recoverable prompts, the `attachment` role description, and the purpose of `inputResponses.usage`. It also clarifies that `verdict` and `category` are the human's ruling, not the agent's. This is exactly the kind of contextual enrichment that helps an agent call correctly.

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 opens with a clear verb+resource: 'Submit an AI prompt and the response it produced to goodbotbad.bot' and immediately establishes the purpose of crowd voting. It distinguishes itself from siblings (complete_pair, get_post, search_posts) by being the only tool that creates submissions, and it explicitly notes it creates a draft rather than publishing, which is a key differentiator.

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 explicit when-to-use guidance: it specifies when to use `turns` vs `manifest` (oversized transcripts), when to use `fixes` (repair of a failure), and when to use `inputResponses` (token usage from the human). It also states a clear don't: 'Do not send the bodies and let the server reject them: that has already disclosed them.' This is model usage guidance, not just a restatement of purpose.

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