get_node_card

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

With no annotations present, the description carries the full behavioral disclosure burden, and it does so thoroughly. It reveals that connectors are read from a probe node on first access, that no undo entry is created, that creation scripts are not run, and that connectors_probed: false with connectors_note means the connectors could not be read rather than being absent. It also explains that unversioned node names resolve to the newest version. This is excellent transparency beyond the schema.

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 and front-loaded, starting with the purpose, then usage guidance, then parameter documentation. It is longer than typical but each clause adds meaningful information, especially the caveats about probe-node behavior and help-text size. A slight tightening around redundant phrases like 'straight from the running Houdini' could improve conciseness, but overall it is appropriately detailed.

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 no output schema and no annotations, the description provides a reasonably complete picture of what the tool returns: connectors in order, parameter details, and help text. It also gives critical edge-case semantics about connector probing. However, it does not fully describe the overall response structure or how errors for invalid node_type/context combinations are reported, which leaves a minor gap for an agent.

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 must fully compensate, and it does. Each parameter is explained: node_type with examples, context with enumerated category values, parm_filter as a substring filter, and include_help with the size/behavior tradeoff. This gives the agent far more semantic meaning than the bare input schema provides.

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 clearly states the tool's function: retrieving an authoritative documentation card for a Houdini node type, including connectors, parameter names/defaults/menus, and help text. It is specific about the resource and the data returned. However, it does not explicitly differentiate itself from closely related siblings like get_node_info, get_parameter_schema, or explain_node, though the focus on 'authoritative doc card' and parameter correctness implicitly separates it.

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 description gives explicit guidance on when to use the tool: 'Use this BEFORE setting parameters on a node type you have not used in this session — never guess parameter names.' It also advises using include_help=False when only parameter names or connectors are needed. It lacks explicit exclusionary guidance against sibling tools, but the context is clear enough for an agent to select it for pre-parameter-setup lookups.

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