card_get

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered, but the description adds little beyond it. 'Returns the new Card' is confusing (a get returning something 'new'?) and it never says what happens when note_id is omitted, which is the key behavioral question for a zero-required-param tool.

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?

Very short, but the final sentence ('Returns the new Card') is both vague and slightly contradictory in phrasing, so brevity comes at the cost of a wasted sentence.

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?

There is no output schema, so the description carries the burden of explaining return values, and 'Returns the new Card' is uninformative about shape or fields. The note-vs-card ambiguity and undocumented no-argument behavior leave real gaps for a tool an agent must call correctly.

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 100% for the single note_id parameter, so the schema does the documentation work. The description confirms note_id is optional but adds no format, semantics, or fallback behavior beyond that.

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 ('Get details and field values') but conflates the resources: the tool is card_get yet the description says it retrieves a 'note' and returns a 'Card', leaving the agent to guess the relationship. It never distinguishes itself from sibling tools like card_search or card_duplicates.

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?

No statement of when to use this tool versus card_search, card_duplicates, or deck_list. The 'Optional: note_id' fragment hints at a no-argument mode but never explains when to use that mode or what it does.

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