tally_status

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

Goes well beyond the annotations: single-request-at-a-time concurrency across all Bridge processes, a ~10 second bounded per-call wait, the tally_endpoint_busy and tally_endpoint_lock_unavailable failure modes, the retry_after_s field, and the metadata-only local receipt log with an explicit 'writes nothing to Tally' guarantee. This is exactly the behavioral context annotations cannot carry.

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?

Front-loads purpose well, but the body is a dense run-on spanning error codes, retry rules, and a `today` explanation that mostly concerns outstandings and ledger_masters rather than this tool. The date discussion is scope creep on a zero-parameter status probe and dilutes the core message.

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?

For a no-param read-only probe with no output schema, the description covers failure modes, retry policy, and side effects (local receipt log, no Tally writes) adequately. It never describes the shape of the returned status/identity tuple, which is the one remaining gap.

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?

Zero parameters, so the baseline is 4; the description instead documents the derived `today` value (this computer's calendar date, YYYYMMDD) that other tools consume. That is useful context but is not parameter semantics for this tool itself, so it stays at baseline rather than exceeding it.

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: 'Return loopback endpoint status and observed loaded-company identity tuples.' An agent can tell this is a health/status probe distinct from the data-reading siblings, though the phrasing is jargon-heavy and no sibling is named as an alternative.

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?

Explains the contention model clearly and when refusals occur (another ComplyEaze Bridge process holding the port), plus what to do: retry after retry_after_s for reads, and for post_import only when attempt_recorded is false, otherwise follow verify_import. It does not explicitly frame which situations should trigger calling this tool first, so it stops short of full when/when-not guidance.

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