femm_facts

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

With no annotations, the description carries the full burden. It usefully discloses the filtering behaviour of `query` (returns only sections that mention it) and names the backing file, but says nothing about what a null query returns, output format, or any auth/rate constraints.

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?

Front-loads the resource identity, then the query behaviour, then the actionable advice. Three compact sentences with no filler; structure is sound.

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?

No output schema and no annotations, with an undocumented parameter. The description covers what the tool is and how query filters, but omits the unfiltered-query behaviour and the shape of the returned facts, so an agent is not fully equipped.

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 0% and the single `query` parameter has no schema description, so the description must compensate. It does explain that query acts as a text match returning only mentioning sections, but leaves the null/default behaviour (likely 'all sections') ambiguous.

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 resource — a curated knowledge base of verified FEMM 5 behaviour (command quirks, units, headless support, renamed materials) — which is clearly distinct from procedural siblings like femm_api_search or femm_manual_section. However, no explicit verb is used, and it does not directly name or route against those closest 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?

Offers one usage cue, 'Read this before trusting FEMM 4.2 habits', which implies when it matters. It does not state when to prefer it over the adjacent reference tools (femm_manual_section, femm_api_search, femm_examples_list), leaving the boundary implicit.

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