external_logging_read

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

There are no annotations to rely on, so the description carries the full burden of disclosing behavior. While it identifies that this is a read operation (implying non-destructive), it does not detail what each endpoint actually returns, any required authentication, or the structure of responses, leaving behavioral expectations vague.

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, dense, front-loaded sentence that immediately states the purpose, lists the specific endpoints, and gives two crucial instructions (pass the endpoint name, use list_endpoints). There is zero wasted content; every clause earns its place.

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?

Given the tool's multi-endpoint nature, the description provides the essential mapping mechanism (name parameter) and a pointer to the authoritative list. It does not need to detail return values since there is no output schema and the tool is a read operation, but this is a minor gap given the absence of annotations and output schema; still, it covers the core guidance needed to invoke endpoints correctly.

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 already provides 100% coverage for all parameters, including descriptions for body, query, and path_params. The description adds the critical semantic that 'name' selects among three endpoints and that 'body' is required specifically 'for POST/PATCH endpoints', linking parameters to the tool's internal multi-endpoint logic and going slightly beyond what the schema states.

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 identifies the tool as read operations for Fivetran external logging, enumerating the three specific endpoints it covers, which distinguishes it from sibling read tools that target other API resource categories. It uses specific verbs ('get', 'list') and explicitly lists the endpoint 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 explicitly instructs the agent to pass the endpoint name and to call list_endpoints(category='external-logging') to get the full list, providing direct guidance for tool selection and usage. This adequately directs usage and explains the mechanism for discovering valid endpoint names.

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