Query ICC Plus entities

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description's 'Search' is consistent with those. However, the description adds no behavioral context beyond that: it does not mention result shape, pagination, matching semantics, or the effect of include_values/include_embedded_assets, which are already partially described 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 a single sentence with no wasted words and front-loads the core action ('Search'). It is concise, but the brevity sacrifices the behavioral and parameter guidance needed for a tool with eight parameters.

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 an 8-parameter, no-output-schema tool in a crowded sibling set, this description is not complete enough. It fails to specify return shape, pagination, query semantics, or when this search tool should be chosen over read/schema/export siblings, leaving agents to rely on inference.

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?

With only 25% schema description coverage, the description needed to compensate, but it barely does. It lists plural entity categories such as 'designs', 'addons', and 'requirements' that map imprecisely to the schema's enum values (e.g., row_design_group vs choice_design_group, addon vs selectable_addon), and it gives no meaning for project_id, ids, query, limit, or offset.

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 uses the verb 'Search' and identifies the resource as ICC Plus entities, then lists the entity kinds it covers. This differentiates it from mutation tools like iccplus_update_entity or iccplus_delete_entity, though it does not explicitly contrast with iccplus_schema or iccplus_read_project.

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?

There is no guidance on when to prefer this tool over siblings such as iccplus_schema, iccplus_read_project, or iccplus_export_fragment. The verb 'Search' implies a read/list use case, but no context, exclusions, or alternative routing is provided.

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