Coderbuds

Update Prospect Tool

update-prospect-tool

Internal Coderbuds staff only. Update one prospect: what research found, what stage it is at, what happens next, and whether a person is needed.

needs_action_reason is how you hand a row back without stopping. Several rows in any pass will have a contact who has changed job, a headcount nobody can verify, or a question only Elliot can answer. Park those with the question written in his words, then carry on to the next row.

If the question ends in a choice, send the choices as answer_options. Most of them do — "write to the CEO, wait for the new lead, or skip?" is three options you have already worked out. Passed as options they become buttons; left in the prose they are a blank textarea, and a question that needs composing is a question that waits a day.

When a question comes back answered, the row appears in the answered list with both what you asked and what you were told. Act on it, then pass answer: null to clear the pair — that is what takes it off the queue, and a row nobody clears is read again every run.

Stages: sourced, contacted, replied, trialling, won, closed. Two rules matter — never set contacted yourself (recording a send does that, so the stage always has something behind it), and closed needs a closed_reason a person can read back.

Corrections to research are welcome and expected: a confirmed role, a corrected headcount, a better signal. Say what you verified in signal, and leave qualification_needed describing what is still unconfirmed rather than deleting it.

When you re-check the signal, set checked_on to today. The ICP requires the trigger to be verified on the day the message is written, not the day the row was sourced, and the queue marks a row whose signal was not checked today so that nobody sends on a job advert that came down last week.

Input Schema

TableJSON Schema

Name	Required	Description
`stage`	No	sourced, replied, trialling, won or closed. Not contacted — record the send instead.
`answer`	No	Pass null once you have acted on an answered question, to take the row off the queue. You should not be writing answers yourself.
`signal`	No	What makes this company worth approaching, as you now understand it.
`checked_on`	No	The date you re-checked the signal, as YYYY-MM-DD. Set it to today whenever you have actually looked — an unchecked row is flagged before anybody sends to it.
`contact_url`	No	Profile URL for the contact.
`next_action`	No	The next concrete thing to do about this row.
`prospect_id`	Yes	The prospect to update.
`contact_name`	No	A confirmed contact name.
`contact_role`	No	Their role, as you verified it.
`closed_reason`	No	Required when closing. Why this is not going anywhere.
`answer_options`	No	The answers that question is offering, up to four, each a complete instruction you could act on as written ("Write to Anh-Tho now", "Close it as unverifiable"). Send these whenever your question ends in a choice — they become buttons, and a question answered with a click is answered the same day. Free text stays available, so never narrow a genuinely open question into options to make it clickable.
`needs_action_reason`	No	The question a person has to answer, in their words.
`qualification_needed`	No	What is still unconfirmed. Leave it describing the gap rather than emptying it.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 13, 2026

addedInput schema / properties / checked_on

Added value: +{
+  "description": "The date you re-checked the signal, as YYYY-MM-DD. Set it to today whenever you have actually looked — an unchecked row is flagged before anybody sends to it.",
+  "type": "string"
+}

Changed1 schema field changedSep 13, 2026

addedInput schema / properties / answer_options

Added value: +{
+  "description": "The answers that question is offering, up to four, each a complete instruction you could act on as written (\"Write to Anh-Tho now\", \"Close it as unverifiable\"). Send these whenever your question ends in a choice — they become buttons, and a question answered with a click is answered the same day. Free text stays available, so never narrow a genuinely open question into options to make it clickable.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed2 schema fields changedSep 13, 2026

addedInput schema / properties / answer

Added value: +{
+  "description": "Pass null once you have acted on an answered question, to take the row off the queue. You should not be writing answers yourself.",
+  "type": "string"
+}

changedInput schema / properties / needs_action_reason / description

Previous value: -"The question a person has to answer, in their words. Pass null to clear one that has been answered."New value: +"The question a person has to answer, in their words."

AddedSep 12, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations are empty, so the description carries the full burden and largely meets it: it discloses the audience restriction ('Internal Coderbuds staff only'), the side effect of clearing an answer pair (takes the row off the queue), that unchecked signals get flagged before sending, that `closed` requires a readable reason, and that corrections should preserve qualification_needed rather than delete it. These are exactly the mutation semantics an agent needs and cannot get from the schema alone.

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?

Front-loaded purpose sentence, then bolded lead-ins that make each rule scannable, and every paragraph encodes an operational rule rather than filler. It is long, however, and a few points restate the schema docstrings (e.g. the checked_on rationale appears in both places), so it is not maximally tight.

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 13-parameter mutation tool with no annotations and no output schema, the description covers stages, transition rules, and queue mechanics well. It never states whether omitted fields are left unchanged (the key behavior for a partial-update endpoint) and says nothing about failure/response shape, which is the main remaining gap.

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

Parameters5/5

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

Schema description coverage is 100%, so the baseline would be 3, but the description adds genuine semantics beyond the schema: needs_action_reason is framed as the escalation channel, answer_options are explained as buttons versus a prose question that stalls, and `answer: null` is explained as the queue-clearing action rather than a free string. That is real added meaning over the field docstrings.

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

Purpose5/5

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

Opens with a specific verb+resource ('Update one prospect') and immediately enumerates the kinds of fields it touches (research findings, stage, next action, human escalation). It also distinguishes itself from a sibling mechanism with the rule 'never set `contacted` yourself (recording a send does that)', which routes the agent to record-prospect-outreach-tool rather than this one for that transition.

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

Usage Guidelines5/5

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

Gives explicit when-to-use conditions for each non-obvious parameter: park blocked rows via needs_action_reason, send answer_options when a question ends in a choice, clear an answered question with `answer: null`, set checked_on when the signal is actually re-verified today. It also states when-not ('never set contact') and the prerequisite for `closed`.

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

All Coderbuds tools Inspect

Try in Browser

Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?