refresh_source

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

No annotations are provided, so the description carries the burden. It does disclose a key behavioral trait: the tool only returns the URL and does NOT perform fetching ('ContextForge does NOT fetch'). However, it does not describe return format, error behavior, or whether the ref needs to correspond to an existing subtopic, which would be useful given the absence of 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 efficient and well-structured, with the core sentence first followed by a helpful clarifying note about ContextForge's non-fetching behavior. Every sentence earns its place; there is zero waste.

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?

The tool has a single param, an output schema, and clear sibling context (import_content is the companion). The description explains the workflow (refresh → fetch externally → import_content) and the tool's limitation. It's reasonably complete for a simple one-param tool, though it could explain the relationship between the input ref and the returned url in more detail.

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 only 1 parameter and 0% schema description coverage, the description must compensate. It mentions 'ref' in passing ('import_content again with the same ref') and implies the ref identifies the subtopic. However, it doesn't explicitly explain what format the ref should take or how it relates to the returned source_url. With only one param, this is a modest gap but the description provides partial context.

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 returns the source_url for a subtopic so the caller can re-fetch. The verb ('Return') and resource ('source_url for a subtopic') are specific. It could be slightly clearer about what 'subtopic' and 'ref' mean in the ContextForge context, but relative to siblings (import_content, get_context), it's fairly distinguishable.

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: when the caller needs to re-fetch fresh content. It also explains what NOT to do — 'ContextForge does NOT fetch' — and directs the caller to use another MCP tool or HTTP fetcher, then call import_content again with the same ref. This is excellent guidance that prevents misuse.

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