refresh

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

With no annotations provided, the description carries the full burden and does so convincingly: cache-first with a 24h TTL, global pacing at 1 req/s, an honest user agent, and a circuit breaker that stays open on 403/429 by design. These are non-obvious operational traits an agent could not infer from the schema, and they define the failure mode explicitly.

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 dense sentences with zero filler; the core action is front-loaded, followed by the id format and then the failure policy. Every clause carries distinct 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?

For a two-parameter fetch tool with no annotations and no output schema, the description covers caching, rate limiting, id format, and error behavior well. It does not state what the tool returns or whether a fetch persists data anywhere, which is a minor but real gap given no output schema exists to fill it.

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 already 100%, which sets a baseline of 3, and the description goes beyond it by defining the two valid source_id namespaces ('project:<slug>' and 'listing:<slug>') rather than just giving one example as the schema does. The force parameter's effect (bypassing the 24h cache) is only explained in the schema, not reinforced in prose, keeping this from a 5.

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?

States a specific verb and resource: fetch one source from korter now, scoped to a single source_id. It is distinguishable from read siblings like get_project because it forces a network fetch rather than a local read. It stops short of explicitly naming an alternative tool or contrasting with 'track' (which presumably refreshes recurring sources), so sibling differentiation is implied rather than stated.

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 conveys context through caching and pacing details (cache-first, 24h TTL, 1 req/s), which implies the tool should be used sparingly for one-off fresh fetches. It also states the operating stance ('this tool stops instead of evading') when blocked. However, it never says when to prefer this over track, get_project, or search_* , leaving the selection criteria to inference.

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