upsert_context

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

No annotations are present, so the description carries the burden of behavioral disclosure. It discloses a meaningful side effect: 'Clears any previously stored source_url/source_name when content is overwritten without source metadata.' This is genuinely valuable behavioral transparency. However, it doesn't describe what happens on failure (e.g., if parent doesn't exist), return format, or whether overwrite is atomic. Decent transparency but incomplete for a mutation tool with zero annotation coverage.

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 and front-loaded with the core purpose in the first sentence. The additional behavioral note about source metadata clearing is worth the space. The blockquote formatting of the warning adds structure. No wasted verbiage, though the line breaks are stylistic.

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?

With no annotations and an output schema present but 0% parameter coverage, the description is notable for disclosing the source_url/source_name clearing side effect. However, it's short on several fronts: no mention of what happens when ref doesn't resolve or parent doesn't exist (error behavior), no format guidance for ref, and no distinction between create vs overwrite semantics beyond the opening verb. For a data-mutating upsert operation touching a complex content hierarchy, this is incomplete.

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 compensate. It explains 'ref' implicitly as 'a subtopic ref' and mentions 'content' as the subtopic's full content. However, it doesn't clarify the ref format (how to reference a subtopic), whether content has constraints (length, format), or what 'subtopic' means in the broader data model. With 2 parameters at 0% coverage, the description provides only minimal compensation—the match on the ref meaning is the most useful addition.

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 'Create or overwrite a subtopic's full content' with a specific verb (upsert) and resource (subtopic content). It distinguishes itself from append_context (the sibling would be for adding to existing content rather than overwriting it), though it doesn't explicitly name that sibling. Clear purpose overall.

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 notes 'Requires a subtopic ref' and 'Parent entity must already exist', giving some prerequisite context. However, it doesn't explicitly explain when to prefer this over append_context or how it differs from alternative write operations. Usage context is implied rather than explicitly stated with exclusions or alternative recommendations.

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