java_search

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

With no annotations, the description carries the full burden and does well: it discloses the ranking precedence (exact > startswith > substring > fuzzy), the all-tokens-must-match constraint, that Spring sections appear as pseudo-entries, and the return shape including an index_stale flag. It omits any auth, rate-limit, or index-refresh behavior, but the non-obvious search semantics are covered.

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-loaded with the purpose, then ranking rules, then the return contract — every sentence adds information rather than restating the name. Slightly dense, but nothing is padding and the ordering follows how an agent would consume it.

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 no annotations and no output schema, the description supplies the return shape and the ranking/matching behavior an agent needs to interpret results. The remaining gap is the undocumented 'limit' parameter; otherwise it is sufficient for a two-parameter read-only search.

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 schema only labels the fields 'Query' and 'Limit'. The description meaningfully explains query semantics (per-token matching, fuzzy fallback, name-based lookup), which compensates for the required parameter, but the 'limit' parameter is never mentioned or bounded, leaving one of two parameters undocumented everywhere.

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: 'Search JDK classes and Spring Boot reference sections by name.' This clearly separates it from spring_search_concepts or spring_reference, though it never names a sibling explicitly, so an agent must infer the boundary.

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?

Usage is implied rather than stated: the 'by name' framing and pseudo-entry note suggest this is the lexical/name lookup tool versus conceptual search. There is no explicit when-to-use, when-not-to-use, or alternative tool named, so the agent has to reason about routing itself.

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