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?

Annotations indicate readOnlyHint=false (writes), openWorldHint=true (external interaction), destructiveHint=false. The description correctly and thoroughly explains behavioral traits: nothing is published immediately, secrets auto-rejected, personal data redacted, oversized transcripts handled via manifest. One minor gap: it doesn't explicitly state that the server enforces size limits, but the manifest workaround is described. 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?

The description is dense and comprehensive but notably long. Every sentence earns its place for a complex multi-step tool, yet it could benefit from clearer sectioning or bullet-like formatting for quicker parsing by an AI agent. The front-loading is acceptable (core submission action first), but the wall of text reduces scanability.

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 tool's high complexity (11 parameters, nested objects, multiple workflows) and presence of an output schema, the description covers almost all critical behavioral paths: draft creation, confirmation URL, secret detection, manifest flow, repair submission, token handling. Slight lack on what the output schema contains (the reply structure) but output schema itself provides that.

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 73%, but the description vastly enriches understanding of parameters like manifest vs turns, fixes lifecycle, usage (human-provided, not AI-generated), and inputResponses. It explains roles not obvious from schema (e.g., attachment for non-text content) and nuances like quoting verbatim vs using objective.

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 is for submitting an AI prompt-response pair to goodbotbad.bot for crowd voting. It distinguishes itself from siblings like search_posts/get_post by explaining the submission lifecycle (draft creation, human confirmation step).

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 extensive when-to-use guidance, including when to send manifest instead of turns for oversized transcripts, how to handle repairs via fixes, and how to respond to inputRequired replies. It also clarifies when NOT to send bodies (to avoid disclosure) and distinguishes this tool from the human's own token logging.

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