Read TIA Export Index

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real behavior: the default payload is a compact summary, with includeCoverageIssues and includeProfile described as opt-in expansions. Remaining gaps are error behavior when the index file is missing and any size/limit implications.

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?

Three tight sentences, front-loaded with the core action and the file it targets, then the opt-in expansions. Nothing is padded, though the enumeration of PLC families is minor detail that consumes space without changing a call decision.

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 six parameters, no output schema and zero schema descriptions, the description supplies only a partial picture of what comes back and how the four unexplained flags alter it. An agent could invoke it correctly but would be guessing about limit, includeCalls/includeItems, and failure modes.

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?

Schema description coverage is 0% across six parameters, so the description carries the full burden, yet it explains only includeCoverageIssues and includeProfile. exportDir, limit, includeCalls and includeItems receive no meaning at all — notably limit, whose 1-500 range and truncation behavior are entirely undocumented.

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?

States a specific verb and resource: reading compact summary metadata from an existing _codex_index/tia-export-index.json. That distinguishes it from export/builder siblings, though it never names tia_list_export_indexes or tia_export_project_index explicitly as the alternatives.

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 phrase 'from an existing ... json' implies this is a read of a previously built index rather than a fresh export, which is useful usage context. However, there is no explicit when-to-use/when-not statement, no mention of what to do when the index is absent, and no routing to sibling tools.

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