Skip to main content
Glama
syrian963

django-chainsaw-mcp

by syrian963

bypassed_effects

Read-onlyIdempotent

Identifies Django bulk operations that bypass model save() signals and receivers, highlighting where side effects like cache invalidation or search index updates may be missed.

Instructions

Bulk writes that skip everything the model's save() chain promised.

what_happens_on says saving an Order creates an Invoice. That is true for
order.save() and false for Order.objects.bulk_create(), .bulk_update() and
.update(): they go straight to SQL, so no save() override runs and no
pre_save/post_save receiver fires. Django documents this in one sentence
per method; nothing at the call site says it.

The finding is not "bulk_create bypasses signals" but this call, on this
model, skips these named effects - the receivers, the overridden save(),
the models that would have been written, transitively. A cache that never
gets invalidated and a search index that quietly drifts are both this.

Only models whose chain does something are reported. QuerySet.delete() is
not listed: Django sends delete signals per object, so that chain fires.

Args:
    search_path: directory to scan. Defaults to the project root.
    model: restrict to one "app_label.ModelName".

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
modelNo
search_pathNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.3

TDQS

A4/5.0
Behavior4/5

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

The description discloses that only models with meaningful chains are reported, that QuerySet.delete is excluded, and why. It also describes the real-world consequences (stale cache, drifting search index), which adds value beyond the readOnly/idempotent/destructive annotations. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than average but front-loads the core idea, then adds necessary context, exclusions, and an Args section. The examples of cache invalidation and search-index drift earn their place, though a sentence or two could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a code-analysis tool with an output schema and safety annotations, the description covers scope, exclusions, and parameters. It sufficiently prepares an agent to call it correctly, though it relies on the output schema for result-shape details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the Args section compensates by explaining search_path defaults to project root and model restricts to an app_label.ModelName. It doesn't explicitly state that omitting model scans all models, but 'restrict to one' implies it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the resource as bulk-write calls that bypass the model save() chain and explains the finding scope, contrasting it with what_happens_on. It lacks an explicit verb like 'find' or 'scan' in the opening sentence, but the content makes the purpose clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explains when the tool is relevant: for bulk_create, bulk_update, and update calls on models whose save chain has effects, and explicitly excludes QuerySet.delete() because delete signals fire. It references what_happens_on to set context, though it does not give an explicit 'use this instead of X' rule.

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