search_in_collective

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

The description mentions returning 'matching page metadata' but adds little beyond the readOnly and idempotent annotations. It does not elaborate on side effects (though none are expected), pagination, or error behavior. Since annotations already cover the read-only nature, the description provides minimal additional behavioral context.

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 concise and well-structured: two sentences that state the action, scope, and return type without redundancy. It is appropriately sized for the tool's simplicity and avoids unnecessary detail.

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?

While the description is clear, it lacks contextual details such as what 'content' refers to (e.g., page body, title, tags), what 'metadata' includes, or how results are ordered. Given the absence of an output schema, the description could be more complete to fully inform the agent about the expected behavior.

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?

The schema covers 2 parameters but only 'query' has a description ('Search text.'). 'collectiveId' is not described, and the tool description does not clarify its meaning or expected format. With 50% schema coverage and no compensation in the description, parameter semantics are weak.

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 for pages by content within a specific Collective and returning matching page metadata. The verb 'search' and the resource 'pages' are explicit, and the scope is narrowed to a specific Collective, distinguishing it from the sibling 'search' tool which likely operates globally.

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 when searching within a specific Collective, but it does not explicitly contrast this with the sibling 'search' tool or other alternatives. It lacks guidance on when to choose this tool over list_pages or the general search, leaving the agent to infer the appropriate context.

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