trmnl_catalog_search

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context. It does so by disclosing the shape of results (tool names, summaries, tags, effects) and that results mirror real callable tools, which goes beyond the annotations.

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 tight sentences; the core purpose is front-loaded and the second sentence adds non-redundant framing about direct tool exposure. No filler, though the second clause could be woven more cleanly.

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 output schema, the description does well to say results include names, summaries, tags and effects. However, for a search tool with two undocumented parameters and no stated pagination/limit semantics, an agent still lacks the info needed to query it well.

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 0% for both `query` and `limit`, and the description supplies nothing about them. "By purpose" weakly suggests the query matches purposes, but there is no guidance on limit, matching behavior, or defaults — the description fails to compensate for the coverage gap.

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+resource ("Find documented TRMNL API operations by purpose") and clarifies what it yields (tool names, summaries, tags, effects). It is distinguishable from most siblings as a discovery tool, though it never names the closest catalog/meta siblings like trmnl_operation_schema or trmnl_framework_guide.

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 only implied: "by purpose" plus "All API operations are also directly exposed as tools" hints you search here when you don't know the operation name and call the tool directly otherwise. There is no explicit when-to-use, when-not, or named alternative such as trmnl_operation_schema.

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