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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile needs no restating. What the description adds is a freshness rationale — FPL rules change each season and free transfers now roll over up to 5 — which justifies trusting results over memory. It says nothing about how results are ranked, how many are returned, or whether an empty result means 'no guide exists'.

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, both front-loaded with the operative instruction, and the parenthetical topic list maps to real guide categories rather than padding. The list is dense but each item is a plausible agent query, so it earns its space; only the 'penalty takers, fixtures' tail drifts toward sibling overlap.

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-optional-parameter read-only search with no output schema, the agent has enough to call it: it knows the corpus, the triggers, and that both params are optional hints. The residual gap is return shape — titles only vs snippets vs full guide bodies — which matters because read_guide exists alongside it and the split is unexplained.

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%: gw is documented as 'Prefer guides for this gameweek' and query as 'What to look for, e.g. bench boost or GW7 tips'. The description's mention of gameweek tips and chip guides loosely corroborates the parameters but adds no semantics the schema lacks, such as whether both params combine or what happens when both are omitted.

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 names a specific verb (search) and resource (fplcopilot guides), then enumerates the actual content domains covered: scoring, free transfers, chips, DefCon, FDR, gameweek tips, penalty takers. That is far more concrete than the title alone. It stops short of distinguishing itself from the sibling read_guide, leaving the agent to guess whether this is keyword search vs direct fetch, and 'penalty takers' overlaps confusingly with the get_penalty_takers sibling.

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?

"Use this for Fantasy Premier League rules and how-to questions" plus "use these, not memory" gives a clear positive trigger and an explicit override of agent priors about FPL rules. There is no exclusion clause, however: it never says when to prefer read_guide or the structured siblings like get_penalty_takers or get_fixture_ticker over guide search.

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