fetch_current

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: it explicitly states the tool may access the upstream website (external network dependency) and never persists a history capture (persistence behavior). This is valuable transparency about side effects and network behavior not covered by the 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?

Two sentences, no fluff. The first sentence states the action; the second adds the key behavioral caveat about upstream access and non-persistence. Every word earns its place, though it could name alternatives to siblings for a more complete picture.

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?

With an output schema present, the description doesn't need to explain return values. However, 4 parameters with 0% schema description coverage means parameter semantics are entirely undocumented. The tool touches an external website with network implications, and while the constraints are clear (read-only, non-persisting), the parameter meanings and usage patterns are not explained. Adequate for a fetch operation but leaves parameter understanding to inference.

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 0%, so the description does not explain any parameters. The description contributes no parameter-level detail. However, there is a rich output schema present, which reduces the burden on parameter documentation somewhat. The schema itself provides names (site, limit, params, path_type) but no semantic meaning, leaving the agent to guess at what 'path_type' or 'params' control.

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 clear verb+resource: 'Fetch a current board.' It distinguishes from sibling tools by emphasizing 'current' (versus history-oriented tools like query_history, search_history, get_trend_series). However, 'board' is a domain-specific term not otherwise defined, and it doesn't explicitly name alternatives. The purpose is clear but somewhat generic without deeper context about what a 'board' represents.

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 usage context (fetching current data rather than history) by contrasting with the upstream website, which helps distinguish from the history-based siblings. It notes 'may access the upstream website but never persists a history capture,' which clarifies it's a live-fetch operation. However, it doesn't provide explicit when-to-use vs when-not-to-use guidance or name specific alternative tools.

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