log_fields

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description goes far beyond annotations by disclosing the return envelope format, guaranteeing the result is complete ('No limit — every matching field is returned'), and explaining that truncated is always false. This gives the agent clear expectations about pagination and result completeness.

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?

Every sentence serves a distinct purpose: purpose, usage, parameter details, and complete return envelope. The structure is front-loaded with the READ action and purpose, and the description is appropriately sized—detailed but without irrelevant filler.

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?

The tool has no output schema and only two optional parameters, yet the description covers the full return shape, pagination behavior, and completeness guarantee. It provides all necessary context for an agent to use the tool correctly without ambiguity.

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 descriptions cover 0% of parameters, so the description carries the full burden. It defines both 'name_filter' as 'optional case-insensitive substring' and 'target' as 'target name from config', adding meaningful semantics beyond the schema's bare titles and default nulls. This fully compensates for the lack of schema 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 opens with '[READ] List the extracted fields available to use in query filters,' which clearly states the verb and resource. It further distinguishes the tool from siblings by explicitly mentioning use before 'log_search / log_aggregate,' aligning with the sibling tool names.

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 provides explicit usage guidance: 'Use this to discover valid field names before filtering log_search / log_aggregate.' This tells exactly when to use the tool and implies it is a prerequisite for other log tools. It also clarifies the optional parameters, giving immediate practical context.

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