parseltongue_register_document

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

With no annotations provided, the description carries the full burden. It explains the side effect of registration (fact extraction becomes possible with :evidence block citations), which goes beyond the basic mechanical description. It doesn't address things like whether re-registering the same name overwrites, whether session must exist, or content size limits, but the evidence-citation behavior is genuinely useful behavioral context.

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 compact, front-loaded with the primary purpose, includes an Args block and Returns block, and adds the important evidence-citation detail early. No wasted prose. Slightly more verbose than strictly necessary, but the structure is clear and scannable.

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 an output schema available for the JSON return, so the Returns line is sufficient. The tool has only 3 simple string parameters with no nesting, making it moderately simple. The description covers purpose, side-effect behavior, parameters, and return type. It doesn't address edge cases (duplicate names, non-existent session), but for a simple registration tool this is reasonably complete.

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. It provides meaningful semantics for all three parameters: session_id as 'Session ID', name as 'Document name (referenced in :evidence blocks)', and content as 'Document text content'. The parenthetical on name adds real value beyond the schema, explaining how 'name' is used downstream for citation.

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 verb ('Register') and resource ('a source document'), and explains the purpose: 'for evidence grounding' with facts that can 'cite it with :evidence blocks'. It distinguishes from siblings like query, check_consistency, and get_state which operate on already-registered data, whereas this one ingests new documents.

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 explains the mechanism ('Facts extracted from this document can cite it with :evidence blocks'), which implies when use is appropriate — registering documents that should be evidence sources. However, it does not explicitly state when NOT to use it or name alternative tools, and doesn't mention prerequisites like requiring an existing session before registration.

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