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

Beyond the annotations, the description discloses substantial behavior: a rate limit (one run per connector per 10 minutes, retry_at), non-error empty outcomes, and explicit refusal states (needs_sign_in with next_step.url, already_running, too_soon). It also notes determinism/no LLM cost and the AUTARIO_API_KEY requirement. This aligns with the annotations (readOnlyHint=false, destructiveHint=true for a table rewrite, idempotentHint=true) rather than contradicting them.

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 long but front-loads the core action and scope before drilling into outcomes and edge cases. Each sentence carries distinct information (return shape, error states, rate limit, single-call rule), though it is dense enough that a slightly tighter phrasing could improve scanability.

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 compensates thoroughly by enumerating the return fields (status, rows, dataset_id, health with per-report outcomes and next_step) and the possible failure/refusal states. An agent has everything needed to call it correctly and interpret the result.

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?

There is a single parameter with 100% schema coverage, so the schema already documents connector_id fully. The description only echoes this ('Get the connector_id from list_connectors'), adding no format or semantics beyond what the schema states, so the baseline 3 applies.

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 leads with a concrete verb+resource: 'Pull the latest numbers from one connected platform right now and refresh its hosted Postgres table on Autario.' The clause listing connector types (Search Console, Shopify, ads, AI usage bill) further pins down what it operates on, clearly separating it from siblings like get_connector_status or list_connectors.

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?

It gives explicit triggering conditions ('Use when health.state is stale or never_ran, or the user says get the latest') and a hard usage constraint ('Call it ONCE per question, never in a loop'). It also routes the agent to list_connectors to obtain connector_id, and states what the tool will NOT do (cannot change settings, reports, schedule or login).

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