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

Annotations already carry readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only safety profile is established. The description adds genuine value beyond annotations by disclosing that returned event logs are 'sanitized' and that provider-supplied details must be 'treated as untrusted evidence' — a meaningful caveat an agent needs before acting on the data. No contradiction with annotations; 'Show' aligns with readOnlyHint.

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 compact sentence with all three clauses earning their place: the primary mapping behavior is front-loaded, followed by the details-toggle behavior and the trust caveat. It is not wasteful, though the semicolon-joined structure creates a slight run-on feel and buries the trust caveat at the end where it could be missed.

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?

An output schema exists and annotations carry the safety profile, so the return shape and read-only nature are covered elsewhere. However, the description still leaves gaps: it never clarifies what happens when includeDetails defaults to false, how the raw transaction relates to portfolio/workspace refs, or what the 'mapping' view actually contains. It is adequate but not complete for a 4-parameter tool with zero parameter documentation in the schema.

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%, so the description carries the full burden of explaining parameters. It only marginally hints at includeDetails via 'request details for sanitized blockchain event logs and decoded contract function calls,' and never explains workspaceRef, portfolioRef, or rawTransactionId beyond their self-evident names. No format, scope, or relationship details between parameters are given, leaving the agent to guess how the refs constrain the lookup.

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 uses a specific verb-resource pair ('Show how one source transaction maps to wallet movements and accounting transactions') and distinguishes the tool's scope from accounting-level siblings like get_journal_entry or get_lot_ledger by centering on raw blockchain data. However, the purpose is somewhat blended — the name implies simple retrieval ('Get Raw Transaction') while the description leads with a lineage/mapping view and then pivots to detail requests, which slightly muddles what the primary deliverable is.

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?

There is no guidance on when to use this tool versus alternatives such as list_raw_transactions, get_portfolio_transaction, or get_journal_entry. No when-not-to-use conditions, prerequisites, or sibling comparisons are provided. The only implicit signal is the name plus the mapping language, which does not tell an agent which of the 46 sibling tools to prefer in a given situation.

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