tally_connection_status

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

With no annotations provided, the description carries the full burden, and it succeeds. It discloses a critical non-obvious behavior: this tool never answers from the response cache, so a green result means TallyPrime answered just now. It also states the tool is read-only, returns error details with fix suggestions, and does not expose accounting data. This is far beyond what annotations would typically provide.

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 well-structured with clear capitalized section headings like WHEN TO USE, RETURNS, DOES NOT RETURN, and PAGINATION. Every section earns its place: safety, cache behavior, output fields, exclusions, and alternatives. It is detailed but scannable, and the most important purpose statement is front-loaded.

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 zero params, no output schema, and no annotations, the description is remarkably complete. It tells the agent what will be returned on success and failure, what will not be returned, that pagination does not apply, that it is safe to call, and that it can also be used to report version. Nothing needed to invoke or interpret the tool is missing.

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 tool has zero parameters and the input schema is empty, so there are no parameter semantics to document. The description correctly focuses on behavior and return values instead. The 0-parameter baseline of 4 is appropriate because description can add nothing further about parameters.

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 a specific verb and resource: 'Check whether TallyPrime is running and reachable over its HTTP interface.' It also clearly distinguishes this from sibling data-returning tools by stating it returns connection status and version, not accounting data. This makes the tool's role immediately unambiguous.

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 explicitly states when to use the tool: 'as a first step when any other Tally tool fails, or to confirm setup before starting an analysis.' It also gives specific alternative routing, e.g., 'does not tell you which company is loaded — use tally_list_companies for that.' The guidance covers both positive use cases and exclusions.

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