The Bot Wire

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

With no annotations, the description must carry the full burden. It discloses that this is a non-mutating check ('Check how fresh') and mentions the components of the response, but it does not elaborate on potential side effects, permission requirements, or what happens if data is stale. It adds some useful context beyond a bare description but is not deeply detailed.

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, well-structured sentence that leads with the main action and then lists the output details. It is efficient with no wasted words; 'Free' adds a small marketing touch but does not detract from clarity.

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 simplicity (zero parameters, no annotations, no output schema), the description provides a good overview of purpose and the main return fields. It could be more precise about the structure of the response, but for a status endpoint it covers the essential information an agent would need.

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 tool has zero parameters, so the baseline is 4. The description does not need to explain parameters because there are none. It correctly focuses on the output and 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 uses the specific verb 'Check' with a clear resource ('The Bot Wire's data') and defines the scope ('right now') plus the key outputs (item counts, source count, last refresh). This clearly distinguishes it from sibling tools like list_wires, query_wire, and search_news, which serve different purposes.

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 use this tool (when you need current data freshness), but it does not explicitly mention alternative tools or provide exclusions. There is no direct comparison with siblings, but the purpose itself makes the usage context reasonably 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 that the tool returns all wires with conditions, filters, and prices, and notes it is free. However, it doesn't mention side effects (likely none) or return format specifics, so it's adequate but not rich.

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 concise sentences plus 'Free.' It is front-loaded, with no wasted words. Every element adds value.

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, parameterless list tool, the description covers what it does, what it returns, and when to use it. It doesn't include a return schema, but the fields are enumerated.

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 are zero parameters, so the baseline is 4. The description adds context about what the output will contain, which is sufficient.

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 it shows every wire, including trigger conditions, filters, and prices. This goes beyond the title and distinguishes it from siblings like query_wire by positioning it as the discovery tool.

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 'Call this first if you are unsure which wire owns the question,' providing a clear when-to-use instruction. It doesn't explicitly list when-not-to-use or alternatives, so not a perfect 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?

With no annotations provided, the description carries the full behavioral burden. It discloses pricing tiers ($0.005/$0.01), a free preview limit (top 3), and empty-result guidance (switch wires). However, it does not describe the response structure, pagination, or error behavior, which would have made it fully transparent. Still, it goes beyond a generic read-only hint by detailing wire-specific filter syntax and pricing.

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 very long, but every wire entry is necessary to convey the mapping. It front-loads the core instruction and then follows a consistent, scannable pattern (wire -> ask when -> filter -> price). The structure is not 'concise' in word count, but it is appropriately sized for the combinatorial list and avoids redundant prose. The only minor issue is that the 'Free preview' note is buried at the end.

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 that there is no output schema and three parameters, the description is remarkably complete. It explains the wire selection logic, every wire option, filter syntax, pricing, and empty-result behavior. It even covers the difference between getting latest items versus searching (query omitted vs provided). The only omission is the precise response shape, but the 'top 3' preview hint partially addresses that. For a simple query tool, this is more than 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?

Although the schema already covers all three parameters (100% coverage), the description massively enriches them. It defines every valid enum value for 'wire' with a unique 'ask when' condition and the associated filter values, which the schema only labels as 'Which wire to query'. It also clarifies that 'query' is optional ("omit for the latest items") and explains that 'filter' takes wire-specific values, referencing the wire list embedded in the description.

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 specific verb+resource: "Pull the latest items from one specialist wire." It clearly distinguishes itself from siblings (search_news, list_wires) by emphasizing specialist wires and providing a comprehensive wire key mapping. The scope is explicit: given a question, map it to a wire key and pass that key.

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 exhaustive 'ask when' guidance for each of the 50+ wires, telling the agent exactly when to select each wire. It also gives an explicit exclusion behavior: "If results come back empty or all low-relevance, this wire likely does not cover the topic — switch wires rather than re-querying." This is strong usage guidance, though it does not directly compare to search_news, the wire-level guidance is the primary decision point.

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 provided, the description carries the full burden of behavioral disclosure. It reveals that the search is keyword-based (not semantic), provides a 'free preview: top 3 results' limitation, and indicates news sources are polled on every ingest run. This is meaningful behavioral context, though it does not mention return format or pagination details.

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 sentences with no wasted words. It front-loads the primary usage case, then provides the search mechanism, an alternative, and a key limitation (free preview). Every sentence contributes essential information.

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 moderate complexity (3 parameters, no output schema), the description covers the core aspects: purpose, usage, behavioral traits, and parameter hints. It does not detail the exact return structure, but the free preview note implies a limited result set. Overall it is sufficiently complete for an agent to select and invoke the tool 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 coverage is 100%, so parameters are well-documented there. The description adds value by clarifying that the query should contain 'distinctive terms' because it is keyword search, which goes beyond the schema's simple examples. This extra nuance improves parameter understanding.

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 performs a ranked search over 40 curated news sources for general, cross-domain questions, and explicitly distinguishes it from query_wire for domain-specific queries. This makes the purpose both specific and well-differentiated from siblings.

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 explicit when-to-use guidance ('Ask when the question is general, cross-domain, or 'what is happening today'') and when-not-to-use guidance ('For a domain-specific question... prefer query_wire'). It also advises on keyword choice ('send distinctive terms'), which is a practical usage tip.

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