Programscape

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: standings are not qualification claims, "Ask {provider}" means the provider decides with no published criteria, each amount is that program's own figure and never a total, and no provider is ranked. That is exactly the kind of interpretation guidance an agent needs to relay results correctly; only the absence of any note on what gets persisted/saved keeps it from a 5.

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 purpose is front-loaded and the tool's scope is clear, but the body is a long run-on sentence followed by three standing-disclaimer clauses. Those caveats do carry behavioral weight, yet their density makes the actionable content harder to extract than it needs to be.

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 no output schema, so the description must carry the return-value burden, and it does describe the review's three sections qualitatively plus how saving is surfaced. For a two-parameter, nested-input tool with full annotation coverage, this is sufficient, though a hint at the concrete shape of the returned review would make it airtight.

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 100% and both parameters (answers, inferredAnswers) are fully documented in the schema, so the baseline is 3. The description adds only indirect meaning by listing the fact categories the answers cover ("stage, funding, the tools they use, company type and answers to earlier questions") and hinting at carried-forward answers; it does not explain the inferredAnswers round-trip or the unknown-fact semantics that the schema handles.

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?

States a concrete verb and resource ("Returns the review Programscape would show a founder") and enumerates the three parts of the result: a short read of what matters, programs worth their time with standings, and what can wait. It also names the input domain (stage, funding, tools, company type, earlier answers), so the agent knows this is a personalized recommendation, not a catalog lookup. It stops short of explicitly contrasting with search_programs/compare_programs, which would have earned a 5.

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?

"For questions about which startup credits, programs or perks fit a company" gives a clear triggering condition for use. However, it names no alternatives (e.g. compare_programs, search_programs) and states no exclusions, so the agent must infer the boundary itself.

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

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

Annotations already declare the safe read-only, idempotent, non-destructive, closed-world profile. The description adds useful behavioral context that results are grouped as families and deliberately present no winner or score, but it omits return format and any pagination behavior.

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 a single, front-loaded sentence with zero waste. It efficiently conveys the output structure and the neutral comparison stance.

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 the low complexity (two optional enum parameters, no output schema) and rich annotations, the description is nearly complete. It could better explain what a 'family' of programs entails or what the side-by-side output actually looks like, since no output schema is provided.

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 100%, so the two optional enum parameters are fully documented in the schema. The description adds no syntax or format details beyond what the schema provides, making the baseline 3 appropriate.

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?

States a specific verb ('Returns'), resource ('families of programs'), and scope ('across providers, side by side'), which distinguishes it from search_programs and get_program. However, it does not explicitly name the sibling tools it differs from, leaving some inference to the agent.

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?

There is no explicit when-to-use or when-not-to-use guidance. The description implies a comparison use case but never mentions alternatives like search_programs for listing or get_program for details, so an agent must infer context.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is not needed for that. It does add real value beyond the annotations by disclosing the shape of the returned record (offers, agent-tool capabilities, decision-maker, exclusions, sources, date checked) and by hedging with "where reviewed," signalling that some fields may be absent.

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?

One front-loaded sentence with no preamble or filler; the field enumeration is the only bulk and it earns its place by describing the payload. Slightly list-heavy but efficient.

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 output schema, the description must carry return-shape information and it does reasonably well, listing the record's contents and the 'where reviewed' caveat. It omits behavior on an unresolvable or unknown id, which is the main remaining gap for a lookup tool.

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 100%, and the single id parameter is already well documented with examples ("aws.activate-credits", "aws-activate-credits", link, exact name). The description adds nothing about the identifier, so baseline 3 applies.

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?

Names a specific verb and resource ("Returns one program's reviewed record") and enumerates the content of that record, so the agent knows this is a single-record read rather than a list operation. It never explicitly names search_programs as the many-record sibling, so differentiation is implied by "one program" rather than stated.

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?

Usage is only implied: the singular framing plus the id parameter suggest 'use this once you have an identifier.' There is no explicit guidance on how to obtain an id (e.g., search_programs first) and no mention of alternatives such as compare_programs or what happens if the id is unknown.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered; the description still adds real context: it requires the founder's Programscape sign-in, and it explicitly warns that omitting planId never silently resolves to the most recently updated plan. That silent-default warning and the auth prerequisite are behavioral facts annotations cannot express. It does not describe output shape limits or error behavior beyond the multi-plan selection case.

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 intent is front-loaded — payload first, conditional behavior second, auth requirement last — and nearly every clause carries information about returned fields. However, the core sentence is a single sprawling run-on with a doubly nested parenthetical about approval, expiration, award, balance and reminder number, which makes it hard to parse. The content earns its place; the structure does not.

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 no output schema, so the description carries the full burden of describing return values, and it does so exhaustively — including conditional fields (expiration date and award only when approved) and the multi-plan ambiguity path. Combined with the stated auth requirement, an agent has everything needed to call it correctly.

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 100% and the single planId parameter already documents the multi-plan requirement and the no-default rule. The prose restates that same rule rather than adding new syntax or format guidance. With the schema doing the heavy lifting on a one-parameter tool, baseline 3 applies.

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?

It uses a specific verb ("Returns") with a specific resource ("the founder's saved Programscape plan") and enumerates the payload — answers, named company, kept/set-aside programs, per-program progress, next action, result note, lifecycle dates, and current review. An agent can tell this is a read of the founder's own plan object rather than a program catalog lookup. It never names a sibling (e.g. update_my_plan or get_program), so differentiation is inferred from the resource name alone.

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?

It states a clear use case — "For a returning founder asking where things stand or what to do next" — and gives an operational rule for the multi-plan case where omitting planId yields named choices and forces a selection. That covers the main invocation decision. It offers no exclusions or comparisons against alternatives such as whats_changed or compare_programs, so the agent must infer when another tool is the better fit.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds meaningful context beyond that: it is reads-only, the counts-under-3 withholding rule (a privacy behavior), and the required admin sign-in. These are behavioral facts the schema and annotations do not convey.

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?

Front-loads the admin-only constraint and packs the return content into one dense but well-ordered sentence. Every clause carries information, though it is a long single sentence that could be split for readability.

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?

No output schema exists, so the description must convey what comes back, and it does so reasonably by listing categories of results and the withholding rule. Some shape-level detail (format, structure) is absent, but coverage is adequate for a zero-param read tool.

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?

There are zero parameters and schema coverage is effectively 100% (empty object), so the baseline is 4. The description adds no parameter detail because none exist, which is appropriate.

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?

States a specific verb and resource: it returns an admin's partner perks list with concrete sub-content (deals due to re-confirm, linked programs changed/closed, invite-link join counts, last feed read). It clearly scopes to 'admin of a perks list' versus founders. It does not name a sibling tool explicitly, but the scope is unambiguous.

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?

Explicitly states who should use it ('only for the admin of a venture firm's or studio's perks list'), who should not ('A founder gets nothing from it'), and where changes belong ('changes are made on the admin page'). The auth condition is also stated ('Needs that admin's Programscape sign-in').

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior, so the bar is lower. The description still adds useful context: sign-in is required, the deals are presented in the partner's own words and labelled as the partner's terms, and founders without a portfolio receive nothing.

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 definition is front-loaded with eligibility and then explains the return, with no filler sentences. It is slightly dense and could be tightened, but every sentence carries useful information.

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?

For a zero-parameter, read-only tool with no output schema, the description covers eligibility, authentication, what is returned, provenance labeling, and the empty-portfolio case. Nothing essential for correct invocation is missing.

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?

The tool has zero parameters, so the baseline is 4. There is no parameter information that need compensating for, and the description correctly does not invent any parameter semantics.

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 states a specific verb and resource: returns a portfolio's negotiated deals and the public programs it points to. It also distinguishes the tool by eligibility: only founders who joined via a venture firm's or studio's invite link, which separates it from the admin sibling.

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?

It clearly states the condition for use (joined via invite link) and the negative case (no portfolio means no deals), plus the sign-in prerequisite. It does not explicitly name or compare against partner_perks_admin, so the alternative routing is left implicit.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is clear. The description adds the behavioral note that 'a fact the founder hasn't given stays unknown,' which hints at state handling but is vague and doesn't fully explain what that means (e.g., no defaults, requires prior input). With annotations covering safety, this is marginally informative.

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 two short sentences and front-loads the main action. However, the second sentence is cryptic and doesn't clearly earn its place—it leaves the agent guessing about its meaning. The structure is concise but lacks clarity.

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 the tool has no parameters and rich annotations, the description should still clarify its role among siblings and what 'questions' and 'review' mean in this context. The description is too vague and doesn't provide enough context for an agent to understand when and why to use it, especially without an output schema.

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?

The tool has zero parameters, so parameter semantics are not applicable. The baseline for zero parameters is 4, and the description doesn't need to compensate for schema coverage since there are no parameters to document.

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 says it 'returns the shared questions, with their answer options, that shape a founder's review.' While it states a verb (returns) and resource (questions with answer options), the phrase 'shape a founder's review' is vague and doesn't clarify what a review is or how this differs from siblings like build_route or get_program. The second sentence about unknown facts is cryptic and doesn't aid purpose clarity.

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?

There is no guidance on when to use this tool versus alternatives. Sibling tools like build_route or get_program are not mentioned. The description implies it's for retrieving questions that influence a route, but doesn't state the context or prerequisites for calling it.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false; the description adds materially more — that the write is scoped ('Changes nothing else on the plan'), that lowBalanceAt replaces the reminder number, that estimate never sets an expiration date, and that auth is required. It also discloses the response shape even though no output schema exists. No rate limits or failure modes are covered, so not a 5.

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 content is roughly the right size for an 8-parameter nested write, and the purpose is front-loaded. But it is delivered as a single dense run-on sentence with a colon-list that duplicates the unit enum verbatim, making it harder to scan than it needs to be.

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?

For a nested, non-idempotent mutation with no output schema, the description covers the essential unknowns: write scope, auth requirement, that the return value echoes stored balance plus read time and reporter, and that the estimate is display-only. Minor gaps remain around plan selection behavior and error conditions, which the schema partly covers.

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 100%, so every one of the 8 parameters (including nested estimate and lowBalanceAt) is already documented in detail. The description largely restates the schema — unit, asOf, source, reminder threshold — without adding syntax or constraints beyond it. Baseline 3 applies when the schema carries the semantics.

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 first sentence states a specific verb and resource — it records the provider-reported balance for one approved program on the founder's plan — and the later clause 'It is a report, never an estimate or a total... never added to other programs' separates it from aggregation/reporting siblings like compare_programs. No sibling is named directly, so it falls short of a 5.

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?

'Needs the founder's Programscape sign-in' states a prerequisite, and the 'never an estimate or a total, never added to other programs or set against the amount awarded' clause functions as an explicit when-not boundary against aggregation tools. It gives clear usage context but never names an alternative tool to use instead.

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

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

Annotations already declare the mutation profile (readOnlyHint false, destructiveHint false, idempotentHint false), and the description usefully adds traits the annotations cannot convey: the artifact is a temporary draft with a 24-hour lifetime, completion requires an email code rather than a password, and the founder's answers and kept programs are carried into the link. It does not warn that repeated calls are non-idempotent and may produce multiple drafts, which is the main residual gap.

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?

Three short sentences, front-loaded with the action and outcome, then the founder-side step and the expiry. Every sentence contributes a distinct fact — what is created, how it is opened, and how long it lasts — with no filler or restated name.

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 output schema present, the description correctly carries the return value itself (a link) and its lifetime, and it explains the human hand-off step that distinguishes this tool from a normal write. Missing only the failure/repeat-call semantics an agent would want before invoking a non-idempotent create.

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 100%, so the baseline is 3 and the schema already explains all three parameters in depth. The description adds only a light restatement ('with their answers and kept programs in place', 'exactly as returned' for inferred answers) and says nothing extra about how to source or format inferredAnswers beyond the schema.

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 gives a specific verb and resource — saving a founder's review as a one-day draft — plus the distinctive outcome (a 24-hour link that opens on programscape.com with answers and kept programs preserved). That is far more precise than the title alone. It never names or contrasts with the closest siblings (my_plan, update_my_plan), so an agent must infer the boundary itself.

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?

Usage is only implied: the description makes clear this is a hand-off step (the founder finishes it themselves via an email code), which suggests calling it at the end of a review rather than for persisting a finished plan. There is no explicit when-to-use, no when-not-to-use, and no pointer to update_my_plan or my_plan for the alternative paths.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description only needs to add context — and it does: results carry an official source and last-checked date, results preserve the catalog's own order, capability data exists only for reviewed records, and it disclaims that a listing is not an eligibility statement. This is genuinely useful behavioral context beyond the annotations.

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?

Four sentences, front-loaded with purpose and scope before the filtering rules; each sentence adds information. Slight redundancy with the schema's own capabilities description keeps it from a 5, but there is no filler.

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 no output schema, and the description compensates by describing what a result contains (official source, last-checked date, capability list) and the ordering guarantee. Combined with 100% schema coverage and a full annotation set, an agent has everything needed to call it correctly.

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 100%, so the baseline is 3, but the description adds real semantics the schema lacks: capabilities match if the record lists ANY one of the requested values, and results retain catalog ordering. It also clarifies the default/empty behaviors implicitly, though the query/provider params are left to the schema.

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?

States a specific verb and resource (searches a reviewed catalog of startup credits, programs and discounts) and names the provider scope. It is clearly distinguishable from siblings like get_program (single lookup) and compare_programs (comparison) without opening a schema.

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 implies when the tool fits (browsing/filtering the catalog) and explains the capability filter's matching rule, but it never states when to use this versus get_program or compare_programs, nor any exclusions. Usage is inferable rather than explicit.

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

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

Beyond the annotations it discloses partial-update semantics ('Only sent fields change; null clears a field'), cascade behavior (clearing a reported result clears its note), conflict behavior for expectedVersion, the authentication requirement, and what is deliberately left untouched. These are exactly the mutation risks an agent needs, and none of it repeats destructiveHint/idempotentHint.

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?

Front-loads the core action and keeps every sentence informative about behavior. It is dense and some clauses ('a partner answer worked out earlier that the firms sent don't settle is taken back') are hard to parse, costing a little readability.

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?

Covers creation-vs-update, auth, conflict handling, and field-clearing for a 6-parameter nested mutation tool. With no output schema, it doesn't say what a successful save returns (e.g., resulting version or plan), which leaves a small gap for the agent.

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 100%, so the baseline is 3; the description earns above that by explaining plan-id selection rules ('an omitted id never chooses the most recently updated one') and version-conflict semantics. It adds little about keep/setAside beyond the schema text, so it isn't a 5.

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?

States a concrete verb-plus-resource ('Saves answers, program choices and founder-reported progress') scoped to 'the selected Programscape plan', and separately enumerates what progress edits cover. It also implicitly separates itself from save_plan_draft by stating that 'drafts, contacts and financial readings stay as stored'.

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?

Gives clear conditions: creates a first plan when none exists, progress requires an existing kept program, multiple plans require an explicit plan id, and expectedVersion guards against intervening saves. It stops short of naming a sibling alternative (e.g., save_plan_draft) for the draft case, so it isn't a full when/when-not/alternative statement.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structured data. The description adds one useful behavioral detail beyond that: results are 'dated and sourced,' telling the agent the response carries provenance and timestamps. It says nothing about how far back changes are tracked or how completeness is determined, so it is a modest addition.

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?

A single front-loaded sentence with no filler and no repetition of the title. The phrasing 'Programscape's latest checks against the providers' own pages' is slightly convoluted for what is essentially a change feed, but nothing is wasted.

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?

For a one-parameter, read-only tool with rich annotations and full schema coverage, the description supplies the key missing context (output is dated and sourced). With no output schema, more detail on how changes are represented would help, but the essentials for correct invocation are present.

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 100% and the single optional limit parameter is fully documented in the schema (max 10, default 3). The description adds no meaning beyond that, so the baseline of 3 applies.

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?

States a specific verb (returns) and resource (what the latest re-checks against providers' own pages found), which is clear enough for an agent to know this is a change/update feed. It does not explicitly distinguish itself from any sibling, but none of the siblings (search_programs, get_program, compare_programs) overlap with a 'what changed since last check' feed.

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?

There is no when-to-use guidance, no prerequisites, and no named alternative. The phrase 'latest re-checks' implicitly suggests freshness-oriented usage, but the agent is left to infer that this is the right tool for detecting program changes rather than calling search_programs or get_program.

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