scrape_watched_sources

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

With no annotations, the description carries the burden of disclosure. It states the core behavior (fetch and add new items) and implies idempotency via 'new content', but it does not disclose potential side effects such as duplicates, failure behavior, or prerequisites like pre-configured watched sources. This is acceptable but not highly transparent.

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 succinct sentences clearly convey purpose and usage without extraneous information. Every word adds value, and the structure is front-loaded with the key action.

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 simple parameter set and lack of output schema, the description covers the essential purpose and usage well. It could benefit from a note on expected return values or behavior when no new content exists, but these are not critical for a basic scraping tool.

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 100%, so the parameter semantics are fully documented. The description reinforces the parameter's meaning but adds no extra detail beyond the schema. The baseline of 3 applies.

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 function: fetching new content from watched sources and adding it to Burn Flame. It specifies the resource (watched sources) and the action (fetch and add), and distinguishes itself from siblings like fetch_content or list_watched_sources by describing the scraping behavior.

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 recommends calling on a schedule or on demand, providing clear context for usage. It does not explicitly discuss alternatives or exclusions, but given the uniqueness of this tool among siblings, the guidance is sufficient for most cases.

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