confluence_insert_table_row

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not mention permissions, return behavior (e.g., success confirmation or updated page), or consequences of insertion (e.g., irreversible changes). The description only covers parameter semantics, leaving significant behavioral gaps.

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 concise: one sentence stating the action and a bulleted list of parameters. It is front-loaded with the purpose. The 'Args:' format is slightly technical but efficient. No unnecessary words.

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 should cover return values and error conditions. It does not state what the tool returns upon success/failure, nor does it address prerequisites or side effects. It is minimally viable but incomplete for confident use.

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 coverage is 0%, so the description fully compensates. Each parameter is explained: page_id accepts numeric or URL, row_index uses 0-based with -1 for append, values as list of cell strings, and table_index with default 0. The semantic meaning goes well beyond the schema's bare titles.

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 'Insert a new row into a table on a Confluence page,' specifying the verb (insert), resource (row in a table), and context (Confluence page). This distinguishes it from sibling tools like confluence_update_table_cell and confluence_delete_table_row.

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 what the tool does but does not explicitly state when to use it versus alternatives (e.g., when to insert vs. update or delete rows). It implies usage through parameter details but lacks direct guidance on selection criteria.

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