fusion_api_search

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful traits beyond that: it is instant, local, and requires no pod round trip. It also clarifies that limit applies per kind rather than globally, which is valuable behavioral detail not present in the schema.

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 compact and purpose-led. The first sentence states what it does, the second gives the primary usage scenario with a realistic example, and the Args section cleanly documents parameters. No redundant phrasing or unnecessary details.

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 simple two-parameter search tool, the description covers purpose, invocation semantics, parameter behavior, and a realistic workflow example. The presence of an output schema means return-value documentation is not required, and annotations cover the safety profile. The tool is fully scoped against its siblings.

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%, so the description fully compensates. It explains term as a substring match across resource names, field names, and business descriptions, and explains limit as maximum matches per kind. This is significantly richer than the bare schema properties and leaves no ambiguity about either parameter.

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?

Description opens with a specific verb and resource: 'Find REST resources and fields by name or business meaning.' It also includes a concrete example mapping a user phrase to an API field name, which clearly differentiates this search tool from siblings like fusion_describe_table or fusion_search_columns.

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 gives a clear use case: when the user mentions a business concept, use this tool to translate it into the expected field name before asking clarifying questions. It also notes the local, no-pod-round-trip behavior. However, it does not explicitly mention alternatives or when not to use this tool versus nearby siblings.

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