ClockNext: search docs

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals that the tool searches across kinds, returns snippets, and works through concept/api/javascript in order. It also surfaces a critical non-obvious behavior: the docs will not tell you the SDK is JS/TS only, so the tool description compensates for that gap. It does not describe exact return formatting or pagination, but the essentials 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?

The description is lengthy but well-structured with numbered list and bolded key points. Each section adds distinct value: the SDK caveat, the kind ordering, and the typical flow. It is not overly verbose; every sentence contributes to correct tool usage, though it could be trimmed slightly without losing critical information.

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?

Given the tool's moderate complexity (three kinds, SDK restriction, integration scenarios), the description is fully complete. It explains what the tool returns (title, URL, snippet), how to sequence searches, and how to handle non-JS/TS cases. No output schema exists, but the description explicitly states return fields, so the agent knows what to expect.

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%, so the baseline is 3. The description adds meaningful guidance above the schema: it explains the meaning and order of the 'kind' values, clarifies that 'javascript' is only for JS/TS codebases, and provides real-world examples for 'query'. This goes beyond the generic property descriptions.

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's function: searching ClockNext's official documentation and returning the most relevant pages with title, URL, and snippet. It distinguishes itself from sibling tools by emphasizing it is the docs search tool, while other siblings like clocknext_get_doc likely retrieve a specific document. The verb 'search' and specific resource 'docs' are explicit.

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?

Provides explicit when-to-use guidance: 'ALWAYS prefer this over answering from memory' and instructs to call it before explaining concepts or designing integrations. It also gives exclusions by telling users not to use the 'javascript' kind for non-JS/TS codebases, with an alternative ('use api'). It outlines a typical search flow, making alternatives and sequencing clear.

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